Что должно быть в хорошем (читай: полезном) стандарте кодирования?
- Вещи, которые должен иметь код.
- Вещи, которые код не должен иметь.
- Должен ли стандарт кодирования включать определения того, что обеспечивает язык, компилятор или средство форматирования кода?
- А как насчет таких показателей, как цикломатическая сложность, количество строк в файле и т. Д.?
coding-standards
Пересекать
источник
источник
Ответы:
Причины для каждого требования. Таким образом, следование стандарту не становится своего рода культом груза, и люди знают, что можно сменить стандарт, если причина для него больше не применяется, или нарушать стандарт в определенных случаях, когда причина явно не применима ,
источник
Вкладки против пробелов! Я получаю сумасшедшие обновления, когда один из моих коллег случайно вкладывает много вкладок, чтобы пробелы перемещались в хранилище
источник
Соглашения об именах
РЕДАКТИРОВАТЬ: Под этим я подразумеваю Правила именования, а не Правила именования.
Например, Руководство будет
All boolean values should begin with Is/Can/Has/etc when possible
. Правило будетAll boolean values must start with Is
источник
IsCanUpdate
иIsHasChildren
. Конечно, это неправильно, но это было определено в стандарте. И это моя точка зрения: как только вы начнете указывать эти вещи, вы должны убедиться, что вы покрываете все основы, иначе люди сталкиваются с тем, что стандарт не покрывает, или плохо покрывает, и затем они либо пишут что-то неправильное, или они начинают игнорировать стандарт. В любом случае, команда проигрывает.Стандарт кодирования для группы должен включать компилятора для предупреждений и ошибок, которые необходимо устранить.
Программисты должны быть свободны увеличивать количество предупреждений для своего собственного кода, но должна быть базовая линия, чтобы чтение и работа с чужим кодом не загромождали вывод, полученный от компилятора.
Такой стандарт также должен был бы учитывать, как программисты могут отключать такие предупреждения в каждом конкретном случае, если существует исключительный фрагмент кода, который иначе не будет соответствовать.
источник
Некоторые стандарты мне нравятся (я знаю, что их много, но это те, которые я предпочитаю):
источник
Кодирование стандарты помогают немного , когда вы пишете код в первый раз, они помогают много , когда вы или ваша замене, должны обновить код через 2 года.
Идеальный стандарт приводит к коду, где вы можете перейти на любую произвольную страницу в коде и точно понять, что он делает во время первого чтения, потому что
С другой стороны, слишком много произвольных стандартов могут нарушить поток написания кода. Поэтому я считаю, что каждый элемент в предлагаемом соглашении о кодировании должен оцениваться по следующим двум критериям:
Если ни то, ни другое не соответствует действительности, элемент является произвольным и, вероятно, ненужным
Я бы включил в стандарт, который я пишу, следующее:
Для ясности:
Организация файлов: Указание фиксированного порядка для элементов в файле позволяет команде легко перемещаться по другим файлам. Вам не нужно искать, чтобы найти #defines или определения структуры.
Соглашения об именах: последовательное именование способствует удобочитаемости. Но избегайте чрезмерного указания слишком большого количества правил, которое вредит написанию.
Структура кода. Расположение фигурных скобок, уровни отступов, пробелы и табуляции и т. Д. Да, это может быть сильным личным предпочтением, но цель - ясный код. Найдите лучший вариант для команды и придерживайтесь его.
Для правильности:
Рекомендации, специфичные для вашего типа проблемы: правила распределения памяти, параллелизма или переносимости.
«Const Correctnesss», правильное использование
static
иvolatile
т. Д.Правила о макросах препроцессора и другие легко используемые возможности языка.
источник
Вдохновляющие, прагматичные идеи, которые заставляют людей думать, а не негативные ограничения, которые мешают людям думать.
В противном случае вы получите код обезьян, которые боятся идти за бананами .
источник
Что должно быть в стандарте кодирования? Как можно меньше. Меньше, скорее, больше. И с обоснованием, пожалуйста.
Не потому, что я какой-то ковбой-кодер, который не хочет никакого процесса, а потому, что я видел тяжелые спецификации кодирования без какой-либо логики за этим (предположительно): «Я нашел это в сети где-то в 95-м», что в итоге стало бюрократический кошмар для работы.
Некоторые люди, честно говоря, полагают, что, повернув стандарты, они увидят соответствующее повышение «качества» кода и, возможно, благодаря этому будут. В то же время они будут игнорировать архитектуру, производительность, здравый смысл и множество других вещей, которые в конечном итоге имеют значение больше, чем количество строк в файле.
источник
Процедура проверки кода для обеспечения соблюдения стандарта. Да, и найти ошибки тоже.
источник
Какой-то старый добрый здравый смысл не сработает; существует слишком много стандартных документов кодирования, которые работают на нерелевантных моментах (такие элементы, как тип и размер шрифта, являются одними из самых экстремальных, которые я видел).
Лучшее, что нужно сделать, если вы находитесь в группе разработчиков, это поговорить друг с другом и посмотреть на ваш код, сформировать консенсус в отношении того, что приемлемо, и если вам нужно записать основные положения в качестве рекомендаций, но придерживайтесь их как только это руководство. Если вы не можете оправдать какое-либо отклонение от руководящих принципов, вам следует подумать, почему вы это делаете.
В конце концов, ясный и понятный код важнее любого жесткого правила в макете или типографике.
источник
Как уже упоминали другие, покрытие кода тестирования имеет важное значение. Мне также нравится видеть:
Структура проекта. Являются ли тесты частью кода или они находятся в отдельном каталоге project / package /? Код пользовательского интерфейса работает с серверной частью? Если нет, то как он разделен?
Процесс разработки. Написать тесты перед кодом? Принимает ли исправление поврежденных сборок приоритет перед разработкой? Когда проводятся проверки кода и что они должны охватывать?
Управление исходным кодом. Что проверяется когда? Контролируются ли проектные документы и планы испытаний на пересмотр? Когда вы переходите и когда вы помечаете? Сохраняете ли вы предыдущие сборки, и если да, то сколько / как долго?
Стандарты развертывания. Как упакована сборка? Что нужно добавить в заметки о выпуске? Как создаются / контролируются / запускаются сценарии обновления?
Забудьте все это дерьмо о соглашениях об именах, форматировании и о том, сколько строк может быть в функции / методе / модуле. Одно правило: используйте любой существующий стиль в том, что вы редактируете. Если вам не нравится чей-то стиль, выделите его в обзоре кода. Единственным исключением может быть элемент tabs-vs-space, хотя бы потому, что многие редакторы / IDE будут слепо преобразовывать одно в другое, а затем вы уничтожаете свою историю изменений, потому что каждая строка была изменена.
источник
Я думаю, что на самом деле есть две вещи, которые нужно рассмотреть, и я бы на самом деле рассмотрел их по отдельности, потому что к ним нельзя подходить одинаково, хотя я считаю, что обе они важны.
Технический аспект, который я квалифицирую как Стандарт кодирования , как и Херб Саттер и Андрей Александреску с их стандартами кодирования C ++ . Презентация, которую я квалифицирую как стиль кодирования , который включает соглашение об именах, отступы и т. Д.
Стандарт кодирования
Поскольку он является чисто техническим, стандарт кодирования может быть в основном объективным. Таким образом, каждое правило должно быть обосновано. В книге, на которую я ссылаюсь, каждый пункт имеет:
Обоснование и исключения очень важны, так как они суммируют, почему и когда.
Заголовок должен быть достаточно явным, чтобы при проверке нужно было иметь только список заголовков (шпаргалку) для работы. И, очевидно, сгруппируйте элементы по категориям, чтобы было легче их найти.
Саттеру и Александреску удалось составить список всего из сотен предметов, хотя С ++ считается волосатым;)
Стиль кодирования
Эта часть, как правило, менее объективна (и может быть совершенно субъективной). Намерение здесь состоит в том, чтобы гарантировать последовательность, потому что это помогает сопровождающим и новичкам.
Вы не хотите вступать в священную войну о том, какой отступ или стиль скобок лучше здесь, для этого есть форумы: так что в этой категории вы делаете вещи консенсусом> большинством голосов> произвольным решением лидера (ов).
Пример форматирования см. В списке опций художественного стиля. . В идеале, правила должны быть достаточно ясными и полными, чтобы программа могла переписать код (хотя вряд ли вы когда-нибудь будете его кодировать;))
Для соглашения об именах я бы попытался сделать класс / типы легко отличимыми от переменных / атрибутов.
Также в этой категории я классифицирую «меры» как:
Разное?
И, наконец, последнее слово, которое редко, если вообще когда-либо обсуждается в стандартах кодирования, возможно, из-за его специфики для каждого приложения: организация кода. Архитектурный вопрос, пожалуй, самый выдающийся, облажайте первоначальный дизайн, и вы будете страдать от него через много лет. Возможно, вам следует добавить раздел для базовой обработки файлов: общие / частные заголовки, управление зависимостями, разделение задач, взаимодействие с другими системами или библиотеками ...
Но это ничто, если они на самом деле не применяются и не применяются .
Любое нарушение должно быть выявлено во время проверки кода, и никакое рассмотрение кода не должно быть в порядке, если нарушение обнаружено:
Очевидно, что изменение правила означает получение «лидера».
источник
Мне нравится формат в Руководстве по проектированию рамок он включает в себя общий раздел и обоснования для руководящих принципов. Самый полезный бит - это детали, начинающиеся с «Делай, не делай, избегай и обдумывай».
Вот пример в разделе « Реализация элементов интерфейса». Ясно, что в нем есть следующие элементы (заметьте, я отбросил обоснования ради бервити)
Это создает хороший общий тон. С помощью Avoid и Study вы можете позволить разработчикам использовать свое суждение. Кроме того, поскольку они являются руководящими принципами, а не правилами, разработчики, вероятно, сочтут их более приемлемыми и, в свою очередь, с большей вероятностью будут следовать им.
источник
Похоже, никто не упоминал о безопасности - в стандарте кодирования вы должны ссылаться на требования к безопасному коду (например, использование входных модулей проверки, запрещение известных слабых функций, таких как strcpy, требования по обработке ошибок и т. Д.)
источник
Примеры.Аккуратно выстроенные, нетривиальные, близкие к реальному миру примеры, в которых используются все правила. Комментарии (не обязательно часть кода), какая часть примера следует какому правилу.
Шаблоны. Не в стиле C ++, а в том, чтобы что-то копировать-вставлять и наполнять live. Намного проще получить этот 24-строчный шаблонный комментарий, если у вас есть ссылка для копирования.
источник
Функция номер один: абсолютный максимум двух страниц.
Это то, что вы хотите, чтобы каждый разработчик прочитал и запомнил. Вам не нужно искать в стандарте каждый раз, когда вам нужно написать новую функцию (или, что еще хуже, новую строку). Таким образом, будьте коротки и соблюдайте только те правила, которые действительно повышают ценность конечного продукта.
источник
Стандарты кодирования действительно несколько пунктов:
Соглашения о кодировании
Лучшие практики
например Никогда не оставляйте пустой Catch после попытки
try { Foo(); } catch { //do nothing }
1) Если Foo () генерирует исключение, это может вызвать другие проблемы в последующих функциях, которые предполагают, что foo прошла успешно.
2) Глобальный обработчик ошибок не будет уведомлять службу поддержки об исключении, когда это происходит на продукт
Среда кодирования
источник
Стандарты кодирования, когда они написаны на бумаге, очень эффективны. Мне нравится, как Go публикует свой стандарт кодирования. Он имеет инструмент
gofmt
для форматирования текста программы в формат. Любая дискуссия о формате кодирования просто приведет к исправлению источниковgofmt
.Что касается того, что формат должен иметь,
if
тела функции, блоков операторов для любых других целей,Когда я читаю чужой код (в основном язык C), если имена переменных / функций не являются интуитивно понятными в контексте проекта, или если он превышает пять уровней отступа, или функции принимают более шести или семи аргументов, или функция выполняется более две или три страницы на экране, становится очень трудно читать и понимать код. Когда его просят сделать улучшения / техническое обслуживание, это только увеличивает сложность. Это заставляет меня хотеть,
gofmt
чтобы программа была написана для каждого проекта (или даже языка) и чтобы каждый файл исходного кода проходил через эту программу, прежде чем она будет зафиксирована в проекте.источник
Мне нравится руководство по стилю Google JavaScript .
В его кратких руководствах есть подробности, если они вам нужны.
источник
Самодокументированный код (комментарии, имена переменных, имена функций и т. Д.)
источник