Что должно быть в стандарте кодирования? [закрыто]

Что должно быть в хорошем (читай: полезном) стандарте кодирования?

• Вещи, которые должен иметь код.
• Вещи, которые код не должен иметь.
• Должен ли стандарт кодирования включать определения того, что обеспечивает язык, компилятор или средство форматирования кода?
• А как насчет таких показателей, как цикломатическая сложность, количество строк в файле и т. Д.?

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

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

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

РЕДАКТИРОВАТЬ: Под этим я подразумеваю Правила именования, а не Правила именования.

Например, Руководство будет All boolean values should begin with Is/Can/Has/etc when possible. Правило будетAll boolean values must start with Is

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

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

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

Некоторые стандарты мне нравятся (я знаю, что их много, но это те, которые я предпочитаю):

• 80% юнит тестов
• Коллективное владение кодом (пишите код, который будут читать ваши товарищи по команде, а не компилятор)
• Пишите комментарии. Напиши, что бы ты сказал новичку.
• Будь проще

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

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

• имена четко описывают, какими данными манипулируют,
• фигурные скобки делают поток контроля ясным,
• комментарии объясняют любой неочевидный алгоритм и т. д.

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

• Помогает ли это правило убедиться в правильности кода ?
• Гарантирует ли это правило помогает , что код Clear ?

Если ни то, ни другое не соответствует действительности, элемент является произвольным и, вероятно, ненужным

Я бы включил в стандарт, который я пишу, следующее:

Для ясности:

• Организация файлов: Указание фиксированного порядка для элементов в файле позволяет команде легко перемещаться по другим файлам. Вам не нужно искать, чтобы найти #defines или определения структуры.

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

• Структура кода. Расположение фигурных скобок, уровни отступов, пробелы и табуляции и т. Д. Да, это может быть сильным личным предпочтением, но цель - ясный код. Найдите лучший вариант для команды и придерживайтесь его.

Для правильности:

• Рекомендации, специфичные для вашего типа проблемы: правила распределения памяти, параллелизма или переносимости.

• «Const Correctnesss», правильное использование staticи volatileт. Д.

• Правила о макросах препроцессора и другие легко используемые возможности языка.

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

В противном случае вы получите код обезьян, которые боятся идти за бананами .

Что должно быть в стандарте кодирования? Как можно меньше. Меньше, скорее, больше. И с обоснованием, пожалуйста.

Не потому, что я какой-то ковбой-кодер, который не хочет никакого процесса, а потому, что я видел тяжелые спецификации кодирования без какой-либо логики за этим (предположительно): «Я нашел это в сети где-то в 95-м», что в итоге стало бюрократический кошмар для работы.

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

Процедура проверки кода для обеспечения соблюдения стандарта. Да, и найти ошибки тоже.

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

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

В конце концов, ясный и понятный код важнее любого жесткого правила в макете или типографике.

Как уже упоминали другие, покрытие кода тестирования имеет важное значение. Мне также нравится видеть:

• Структура проекта. Являются ли тесты частью кода или они находятся в отдельном каталоге project / package /? Код пользовательского интерфейса работает с серверной частью? Если нет, то как он разделен?

• Процесс разработки. Написать тесты перед кодом? Принимает ли исправление поврежденных сборок приоритет перед разработкой? Когда проводятся проверки кода и что они должны охватывать?

• Управление исходным кодом. Что проверяется когда? Контролируются ли проектные документы и планы испытаний на пересмотр? Когда вы переходите и когда вы помечаете? Сохраняете ли вы предыдущие сборки, и если да, то сколько / как долго?

• Стандарты развертывания. Как упакована сборка? Что нужно добавить в заметки о выпуске? Как создаются / контролируются / запускаются сценарии обновления?

Забудьте все это дерьмо о соглашениях об именах, форматировании и о том, сколько строк может быть в функции / методе / модуле. Одно правило: используйте любой существующий стиль в том, что вы редактируете. Если вам не нравится чей-то стиль, выделите его в обзоре кода. Единственным исключением может быть элемент tabs-vs-space, хотя бы потому, что многие редакторы / IDE будут слепо преобразовывать одно в другое, а затем вы уничтожаете свою историю изменений, потому что каждая строка была изменена.

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

• Технический аспект: который направлен на то, чтобы избежать рискованного или некорректного кода (даже если он принят компилятором / интерпретатором)
• Аспект представления: что касается разъяснения программы читателям

Технический аспект, который я квалифицирую как Стандарт кодирования , как и Херб Саттер и Андрей Александреску с их стандартами кодирования C ++ . Презентация, которую я квалифицирую как стиль кодирования , который включает соглашение об именах, отступы и т. Д.

Стандарт кодирования

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

• Название, простое и точное
• Резюме, которое объясняет название
• Дискуссия, которая иллюстрирует вопрос о том, как поступить иначе, и, таким образом, содержит обоснование
• необязательно Некоторые примеры, потому что хороший пример стоит тысячи слов
• необязательный Список исключений, для которых это правило не может быть применено, иногда с обходными решениями
• Список ссылок (другие книги, сайты), которые обсуждали этот пункт

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

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

Саттеру и Александреску удалось составить список всего из сотен предметов, хотя С ++ считается волосатым;)

Стиль кодирования

Эта часть, как правило, менее объективна (и может быть совершенно субъективной). Намерение здесь состоит в том, чтобы гарантировать последовательность, потому что это помогает сопровождающим и новичкам.

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

Пример форматирования см. В списке опций художественного стиля. . В идеале, правила должны быть достаточно ясными и полными, чтобы программа могла переписать код (хотя вряд ли вы когда-нибудь будете его кодировать;))

Для соглашения об именах я бы попытался сделать класс / типы легко отличимыми от переменных / атрибутов.

Также в этой категории я классифицирую «меры» как:

• предпочитают короткие или длинные методы: обычно трудно договориться о том, что такое длинный
• предпочитаю досрочный возврат / продолжение / перерыв, чтобы уменьшить отступы

Разное?

И, наконец, последнее слово, которое редко, если вообще когда-либо обсуждается в стандартах кодирования, возможно, из-за его специфики для каждого приложения: организация кода. Архитектурный вопрос, пожалуй, самый выдающийся, облажайте первоначальный дизайн, и вы будете страдать от него через много лет. Возможно, вам следует добавить раздел для базовой обработки файлов: общие / частные заголовки, управление зависимостями, разделение задач, взаимодействие с другими системами или библиотеками ...

Но это ничто, если они на самом деле не применяются и не применяются .

Любое нарушение должно быть выявлено во время проверки кода, и никакое рассмотрение кода не должно быть в порядке, если нарушение обнаружено:

• исправить код, чтобы соответствовать правилу
• исправить правило, чтобы код больше не выделялся

Очевидно, что изменение правила означает получение «лидера».

Мне нравится формат в Руководстве по проектированию рамок он включает в себя общий раздел и обоснования для руководящих принципов. Самый полезный бит - это детали, начинающиеся с «Делай, не делай, избегай и обдумывай».

Вот пример в разделе « Реализация элементов интерфейса». Ясно, что в нем есть следующие элементы (заметьте, я отбросил обоснования ради бервити)

Избегайте явной реализации элементов интерфейса без веской причины для этого

Рассмотрите возможность реализации членов интерфейса в явном виде, если они предназначены для вызова только через интерфейс.

Не используйте явные члены в качестве границы безопасности.

Как обеспечить защищенный виртуальный элемент , который имеет ту же функциональность , как> явно реализованного члена , если имеется в виду функциональные возможности специализироваться производными классами.

Это создает хороший общий тон. С помощью Avoid и Study вы можете позволить разработчикам использовать свое суждение. Кроме того, поскольку они являются руководящими принципами, а не правилами, разработчики, вероятно, сочтут их более приемлемыми и, в свою очередь, с большей вероятностью будут следовать им.

Похоже, никто не упоминал о безопасности - в стандарте кодирования вы должны ссылаться на требования к безопасному коду (например, использование входных модулей проверки, запрещение известных слабых функций, таких как strcpy, требования по обработке ошибок и т. Д.)

Примеры.Аккуратно выстроенные, нетривиальные, близкие к реальному миру примеры, в которых используются все правила. Комментарии (не обязательно часть кода), какая часть примера следует какому правилу.

Шаблоны. Не в стиле C ++, а в том, чтобы что-то копировать-вставлять и наполнять live. Намного проще получить этот 24-строчный шаблонный комментарий, если у вас есть ссылка для копирования.

Функция номер один: абсолютный максимум двух страниц.

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

Стандарты кодирования действительно несколько пунктов:

Соглашения о кодировании

• эти вещи не нуждаются в причине, кроме "согласованности кодовой базы" для ex. использовать '_' в приватных переменных-членах или нет.
• может быть несколько правильных подходов. Просто нужно выбрать один для согласованности. например обработка ошибок с использованием исключений или кодов ошибок.

Лучшие практики

• эти пункты всегда нуждаются в веской причине с некоторыми наглядными примерами

например Никогда не оставляйте пустой Catch после попытки

try { Foo(); } catch { //do nothing }

1) Если Foo () генерирует исключение, это может вызвать другие проблемы в последующих функциях, которые предполагают, что foo прошла успешно.

2) Глобальный обработчик ошибок не будет уведомлять службу поддержки об исключении, когда это происходит на продукт

• охватывает практики «защитного кодирования», такие как использование утверждений для проверки ваших предположений.

Среда кодирования

• инструменты, которые использует вся команда. например VS 2010, Решарпер, Печь и т.д ..

Стандарты кодирования, когда они написаны на бумаге, очень эффективны. Мне нравится, как Go публикует свой стандарт кодирования. Он имеет инструмент gofmtдля форматирования текста программы в формат. Любая дискуссия о формате кодирования просто приведет к исправлению источниковgofmt .

Что касается того, что формат должен иметь,

• как называть переменные, макросы, константы, литералы, функции и т. д.
• как разместить {,}, (,), [,] когда дело доходит до if тела функции, блоков операторов для любых других целей,
• насколько широкими должны быть отступы,
• сколько символов допускается строка текста
• сколько уровней отступов разрешено, прежде чем код будет отклонен / отправлен для рефакторинга
• сколько строк кода разрешено для каждой функции перед отправкой обратно для рефакторинга
• максимальное количество аргументов, которые может принять функция, прежде чем она будет отправлена ​​обратно для рефакторинга
• Несколько строк комментариев перед тем, как функция начинает кратко объяснять, что она делает, если тело должно превышать одну страницу кода на экране; оставляя, как объект достигается коду в теле функции

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

Мне нравится руководство по стилю Google JavaScript .

В его кратких руководствах есть подробности, если они вам нужны.

Самодокументированный код (комментарии, имена переменных, имена функций и т. Д.)