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

https://softwareengineering.stackexchange.com/questions/15636

coding-standards

22-10-2019
|

Вопрос

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

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

Решение

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

Другие советы

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

Наименование соглашений

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для ясности:

Организация файла: указание фиксированного порядка элементов в файле позволяет команде легко ориентироваться в других файлах. Вам не нужно охотиться, чтобы найти #Defines или определения структуры.
Конвенции именования: постоянная читаемость СПИДа. Но избегайте чрезмерного определения слишком большого количества правил, это наносит ущерб написанию.
Структура кода. Кудрявое размещение скобки, уровни углубления, пробелы против вкладок и т. Д. Да, это может быть сильным личным предпочтением, но целью является четкий код. Найдите лучший вариант для команды и придерживайтесь ее.

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

Лучшие практики, специфичные для вашего типа задачи: правила распределения памяти, параллелистики или переносимости.
"Constrafitys", правильное использование static а также volatile, так далее.
Правила о препроцессорных макросах и других функциях языка легко злоупотребляют языком.

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

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

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

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

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

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

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

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

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

Как упоминали другие, охват теста кода важен. Я также люблю видеть:

Структура проекта. Являются ли тесты частью кода, или они находятся в отдельном проекте/пакете/каталоге? Живет ли код пользовательского интерфейса с бэк-вещей? Если нет, то как это разделено?
Процесс разработки. Записать тесты перед кодом? Убирает ли исправление сломанных сборки приоритетом в разработке? Когда проводятся обзоры кода и что они должны покрывать?
Управление исходным кодом. Что проверяется, когда? Контролируются ли дизайнерские документы и планы тестирования? Когда вы вещите и когда вы помечаете? Вы сохраняете предыдущие сборки, и если да, то сколько/как долго?
Стандарты развертывания. Как упакована сборка? Что нужно выйти в выпускные заметки? Как создаются сценарии обновления/контролируются/запускаются?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Именно в этой категории я классифицирую «меры», подобные:

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

Разное?

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

Но это ничего такого Если они на самом деле не применяются и принудительно.

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

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

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

Мне нравится формат в Руководство по проектированию фреймворта Он включает в себя общий раздел и рациональные рекомендации. Наиболее полезными являются детали, которые начинаются с Do, не избегайте и не учитывайте.

Вот пример в разделе Реализация участников интерфейса явно У него есть следующие элементы (обратите внимание, что я отказался от обоснования ради Бервити)

Избегать Реализация участников интерфейса явно без веских причин для этого

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

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

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

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

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

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

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

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

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

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

Кодирующие соглашения

Этим не нужна причина, кроме того, «согласованность базы кода» для Ex. использовать '_' в частных переменных члена или нет.
Там может быть несколько правильных подходов. Просто нужно выбрать один для последовательности. для бывшего Обработка ошибок с использованием исключений или кодов ошибок.

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

Этим предметам всегда нужна веская причина с некоторыми четкими примерами

для бывшегоНикогда не оставляйте пустой улов после попытки

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

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

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

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

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

Инструменты, которые использует вся команда. для бывшего VS 2010, Resharper, Kiln и т. Д.

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

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

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

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

я люблю Google JavaScript Руководство по стилю.

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

Код самостоятельного документирования (комментарии, имена переменных, имена функций и т. Д.)

Лицензировано под: CC-BY-SA с атрибуция

Не связан с softwareengineering.stackexchange