Создание документа по стандартам кодирования

Я работаю в компании, занимающейся системами управления, где основной работой являются SCADA и PLC , а также другие сотрудники систем управления.

На самом деле, разработка программного обеспечения - это не то, чем занимается компания, за исключением маленьких кусочков, пока не было принято решение о создании внутренней системы управления проектами и оценки.

Этот проект был принят людьми, которые изначально приехали сюда как программисты, а мы в основном младшие.

Проект начинался с малого, поэтому мы документировали только такие вещи, как дизайн, базы данных и т. Д., Но мы никогда не соглашались с форматом / соглашениями по кодированию.

Мы начали использовать StyleCop, чтобы удостовериться, что у нас хорошо документированный код, но я чувствую, что нам нужен официальный документ для соглашений / практик кодирования, чтобы мы могли продолжать придерживаться хорошего стандарта, и если в будущем будут какие-либо более серьезные разработки, кто бы над этим не работал имеет хорошую опорную плиту

В этом и заключается проблема, я понятия не имею, как составить документ для соглашений и стандартов кодирования, все, что я могу придумать, это примеры хорошей или плохой практики (например, случай верблюда, когда именуются переменные, избегают венгерской нотации и т. Д.), Мы все достаточно компетентные программисты (очевидно), но у нас просто нет хартии для такого рода вещей.

Чтобы подчеркнуть это, у меня вопрос: каковы основные аспекты и содержание хорошего документа по стандартам кодирования?

Каковы основные аспекты и содержание хорошего документа по стандартам кодирования?

1. Будучи при поддержке инструментов , которые дают возможность автоматизированной проверки кода . Если я знаю, что не могу взять на себя управление версиями какого-либо фрагмента кода, который не соответствует некоторым правилам, мне будет рекомендовано следовать этим правилам в моем коде. Если, с другой стороны, какой-то другой программист написал где-то, что мне нужно следовать правилу, я не буду об этом заболтать.

2. Быть хорошо продуманным, а не вашим личным мнением . Вы не говорите прямо: «отныне мы больше не используем регионы, потому что я не люблю регионы». Скорее, вы бы объяснили, что регионы стимулируют рост кода и не решают никаких серьезных проблем .

   Причина в том, что в первом случае ваш коллега отвечал: «ну, мне нравятся регионы, поэтому я все равно буду их использовать». Во втором случае, с другой стороны, это заставит людей, которые не согласны прийти с конструктивной критикой, предложениями и аргументами, в конечном итоге заставить вас изменить свое первоначальное мнение.

3. Быть хорошо документированным . Отсутствие документации создает путаницу и возможности для интерпретации ; путаница и возможность интерпретации приводят к разнице в стиле, то есть то, что стандарты хотят подавить.

4. Будучи широко распространенным, в том числе за пределами вашей компании . «Стандарт», используемый двадцатью программистами, является менее стандартным, чем стандарт, известный сотням тысяч разработчиков по всему миру.

Поскольку вы говорите о StyleCop, я предполагаю, что приложение написано на одном из языков .NET Framework.

В этом случае, если у вас нет серьезных оснований действовать иначе, просто придерживайтесь рекомендаций Microsoft. В этом есть несколько преимуществ, а не создание собственных стандартов. Взяв четыре предыдущих пункта:

1. Вам не нужно переписывать правила StyleCop, чтобы они соответствовали вашим собственным стандартам. Я не говорю, что сложно писать свои собственные правила, но если вы можете избежать этого, это значит, что у вас больше времени, чтобы заняться чем-то полезным.

2. Рекомендации Microsoft очень хорошо продуманы. Есть вероятность, что если вы не согласны с некоторыми из них, это может быть потому, что вы их не понимаете. Это был именно мой случай; Когда я начал разработку на C #, я обнаружил, что несколько правил совершенно глупы. Теперь я полностью согласен с ними, потому что я наконец понял, почему они были написаны таким образом.

3. Рекомендации Microsoft хорошо документированы, поэтому вам не нужно писать собственную документацию.

4. Новые разработчики, которые будут наняты в вашей компании позже, возможно, уже знакомы со стандартами кодирования Microsoft. Есть некоторые шансы, что никто не будет знаком с вашим внутренним стилем кодирования.

Первое, на что следует обратить внимание, это то, что документ о стандартах кодирования не о правильном и неправильном Речь идет не о хорошем и плохом или о том, какой метод лучше.

Цель документа по стандартам кодирования состоит в том, чтобы убедиться, что весь код спроектирован, написан и выложен одинаково, чтобы разработчику было легче переключаться с одного человека на другой без необходимого изменения менталитета для чтения чужого стиля.

Это все о единообразии, и ничего о "правильно и неправильно"

Имея это в виду некоторые вещи, которые вы должны уточнить в документе о стандартах кодирования:

Соглашения об именах

Как вы будете называть ваши методы, переменные, классы и интерфейсы? Какую нотацию вы будете использовать?

Кроме того, что-то еще, включенное в наши стандарты, было разделением стандартов для SQL, поэтому у нас были похожие имена для таблиц, процедур, столбцов, полей идентификаторов, триггеров и т. Д.

вдавливание

Что вы будете использовать для отступа? Отдельная вкладка? 3 пробела?

раскладка

Будут ли фигурные скобки находиться на той же строке, что и строка метода открытия? (вообще java) или на следующей или отдельной строке? (обычно C #)

Обработка исключений / регистрация

Каковы ваши стандарты обработки и регистрации исключений, все это домашнее или вы используете сторонний инструмент? Как это должно быть использовано?

Комментирование

У нас есть стандарты, предписывающие грамматическую правильность, и то, что комментарии начинаются на строке до или после, а не на одной строке, это повышает удобочитаемость. Будут ли комментарии иметь отступ на ту же глубину, что и код? Примете ли вы те границы комментариев, которые используются вокруг больших текстов?

Как насчет \\\ on Методы для описаний? Это будет использоваться? Когда?

Экспозиция

Должны ли все ваши методы и поля реализовывать самый низкий уровень доступа?

Также важно отметить. Хороший документ по стандартам может помочь в рассмотрении кода, соответствует ли он этим минимальным стандартам?

Я едва поцарапал поверхность того, что может войти в один из этих документов, но КИСС

Не делайте это длинным, скучным и невозможным, или просто не соблюдайте эти стандарты.

Я проходил этот процесс несколько раз. И самым успешным (хотя и не совсем удачным) был подход - взять документ «Стандарты кодирования» от известной компании и изменить его в соответствии с вашими потребностями.

Например, я только что нашел это: http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

В любом случае, держите свой огнемет под рукой.

Ура,

Я ненавижу большинство стандартных документов, потому что они обычно пытаются потеть мелочи и игнорируют общую картину.

Например, почти все из них скажут, как называть переменные или ставить скобки. Это чистый стиль, и он мало помогает правильному кодированию группы разработчиков. Они игнорируют такие вещи, как структура каталогов и макет кода. Я видел стандартные документы, в которых точно указывалось, сколько пробелов ставить между операторами и сколько пустых строк ставить между методами. Все это обычно заканчивается множеством исключений из правила, которое просто показывает, насколько они бессмысленны, а затем они настолько велики, что никто не может им следовать, что опять же высмеивает то, что они пытаются сделать ,

Теперь я использую много разных программных продуктов от разных людей, и у них у всех разные стили. Я просто привыкаю к ​​этому, я не жалуюсь, что не существует общего стиля для всех групп разработки. Пока код является общим стилем для всего проекта, мне действительно все равно, что это за стиль. Поэтому мое первое правило для всех стандартных документов: придерживайтесь единого стиля кодирования в проекте . никто не должен показывать, где скобки, если они все одинаковые. Возьми религиозные войны и запихни их :)

Второе - это макет кода. Когда я беру кусок кода, я хочу видеть, что он выложен по тем же принципам, что и другие, похожие работы. Если у меня есть веб-сервис, я хочу, чтобы имя контракта wsdl было понятным, я хочу, чтобы имя реализации было понятным. Я не хочу, чтобы кто-то придумал совершенно новый и другой макет для файлов и классов. Это означает, что я должен играть в «охоту на код», что является неприятностью. Если он выглядит так же, как и последний проект, над которым я работал, я сразу же могу узнать, где найти то, что я ищу, и это, вероятно, самая большая помощь в работе с чужим кодом, который я знаю. Таким образом, сохраните структуру того, как выложен код (например, папка «Документация» для документов, интерфейсы для интерфейсов и т. Д. - что бы это ни было для вас, но придерживайтесь его).

Также должны присутствовать артефакты кода, поэтому вы должны сказать, является ли ожидаемая обработка ошибок исключениями или кодами ошибок - т.е. Архитектурная функциональность документа, которая используется . В нем также должно быть указано, какой тип ведения журнала использовать и как представить журналы / обработку ошибок пользователю или какую-либо подсистему, используемую для управления кодом на свободе. Я работал в месте, где каждый проект вел свою регистрацию по-разному - было жалко, что в каждом выпуске кода должен был быть свой собственный документ с описанием операций, рассказывающий парням-операционистам, как сказать, что все пошло не так. Журнал событий, файл журнала (в этом случае где), и т. Д. Все действительны здесь. То же самое относится и к другим общим аспектам кода - как его настроить (нет смысла использовать файл .config для некоторых программ, или пользовательскую БД, или параметры командной строки, или реестр для других).

Короче говоря, единственное, что имеет значение, это последовательность . А поскольку огромные документы по стандартам слишком сложны для чтения и запоминания, я предпочитаю просто информировать людей о вещах, которые они не могут видеть (например, об архитектурных стандартах, таких как ведение журнала), и просить их поддерживать код, который они пишут, в соответствии с тем, что есть в настоящее время. А если у вас уже нет кода, тогда вам не нужен документ по стандартам! (ну, пока вы не написали достаточно, чтобы сделать его полезным).

Итак, возьмите из этого основные моменты: не пытайтесь сделать юридический документ , думайте о вещах, которые не только кодируют, но также и как код работает и как код соответствует ожиданиям других людей. Тогда доверьтесь людям делать хороший код, и вы увидите, что они делают. (и если они этого не делают, вы не можете говорить с ними, нет необходимости устанавливать это как закон).

Не, это полная трата времени и энергии. StyleCop великолепен и был создан годами людьми, намного более опытными и умными, чем вы или кто-либо из вашей команды. Обними и люби это! Он ведет вас постоянно, что лучше, чем любой документ, ожидающий того, кто может его потрудиться прочитать.