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

34

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

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

Ответы:

40

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

dsimcha
источник
3
Абсолютно. У каждого элемента в стандарте должно быть четко указано обоснование.
AShelly
4
Иногда нет веской причины для выбора, но желательно, чтобы все делали то же самое. Я не знаю, почему мы все едем направо, используя автомобильную аналогию, но это намного лучше, чем половина справа и половина слева.
Дэвид Торнли
9
@ Дэвид: Это вполне законная причина наличия стандарта кодирования. Если это причина, то это должно быть просто указано как таковое, то есть «Причина: для улучшения согласованности кодовой базы».
дсимча
На самом деле, самое главное , о кодировании стандарта является то , что там есть один. То, что там, действительно вторично.
Йорг Миттаг
20

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

Феде
источник
1
Я согласен от всего сердца!
matiash
2
ИМХО, это единственное , что заслуживает того, чтобы быть в стандарте кодирования.
П Швед
2
ИМХО, это отличный пример того, что стандарт кодирования не должен охватывать.
Бьярке Фрейнд-Хансен
@bjarkef, вы предпочитаете смешанный код табуляции и пробелов?
Jé Queue
19

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

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

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

Рэйчел
источник
3
LPSZ * lppsz_CPP_MrKim_ClassOfStudents [] [];
Матин Улхак
3
-1: Это именно та деталь низкого уровня, которая заставляет разработчиков игнорировать стандарты. С таким же успехом можно поручить всем носить галстуки.
TMN
2
@ TMN: отсутствие соглашений об именах - это именно та вещь, которая заставляет разработчиков отчаянно когда-либо понимать код. Они не должны быть придирчивыми, но несколько общих рекомендаций помогут очень.
Дэвид Торнли
1
@Rachel: Да, у нас был стандарт "все логические свойства должны начинаться с" Is ". Завелись со свойствами вроде IsCanUpdateи IsHasChildren. Конечно, это неправильно, но это было определено в стандарте. И это моя точка зрения: как только вы начнете указывать эти вещи, вы должны убедиться, что вы покрываете все основы, иначе люди сталкиваются с тем, что стандарт не покрывает, или плохо покрывает, и затем они либо пишут что-то неправильное, или они начинают игнорировать стандарт. В любом случае, команда проигрывает.
TMN
1
Вот почему я думаю, что он должен включать в себя Правила, а не Правила, как называть ваши объекты. Точные имена до сих пор остаются за разработчиками. Я отредактирую свой ответ.
Рейчел
10

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

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

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

Макнейл
источник
Согласовано. Другая часть, которую я бы добавил, состоит в том, что если вы оставляете его живым как предупреждение, то к нему нужно обратиться, изменив его или подавив предупреждение. В противном случае предупреждения становятся бесполезными быстро (слишком много в большом проекте), и вы можете отключить их. В VS я предпочитаю, чтобы Предупреждения ломали сборку и заставляли вас иметь с ними дело.
МВД
Разве это не то, что вы должны вставить в свой make-файл, а не в стандарт?
Бьярке Фрейнд-Хансен
@bjarkef: В конечном счете, опции войдут в Makefile, да. Но смысл приведения его в стандарт состоит в том, чтобы стандартизировать то, что необходимо решать. Например, должны ли разработчики всегда создавать идентификаторы сериализации? Команда должна решить, должно ли это быть обязательным или проигнорировано.
Макнейл
@bjarkef: Конечно, но хорошо иметь их в стандартной справке, когда вы начинаете новый проект и вам нужно написать новый make-файл (или ваш новый проект использует что-то кроме Make для своего инструмента сборки).
TMN
9

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

  • 80% юнит тестов
  • Коллективное владение кодом (пишите код, который будут читать ваши товарищи по команде, а не компилятор)
  • Пишите комментарии. Напиши, что бы ты сказал новичку.
  • Будь проще
user2567
источник
Требования, касающиеся охвата модульных тестов, являются одной из самых лучших вещей, которые могут войти в стандарты кодирования.
Адам Кроссленд
Что касается тестового покрытия: почему только 80%? Является ли это примером правила 80/20, где, по вашему опыту, эти 20% потребуют на 100% больше усилий для достижения? Кроме того, что за покрытие? [например, заявление о покрытии? Функция покрытия? Решение о покрытии? Состояние покрытия?]
Макнейл
@Macneil: да, что-то в этом роде. Я обнаружил, что 80% "достаточно хорошо" для большинства классов и это хорошее число. Я когда-то пытался достичь 95%, и это была настоящая трата времени. Конечно, если в некоторых классах легко достичь 100%, продолжайте
Так это заявление о покрытии? Кажется, многие инструменты не дают вам больше, чем это. Какой инструмент вы используете?
Макнейл
Я использую TestDriven.net со встроенным nCover
7

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

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

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

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

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

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


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

Для ясности:

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

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

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

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

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

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

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

AShelly
источник
6

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

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

Алан Пирс
источник
4

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

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

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

Родни Гицель
источник
3

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

Дима
источник
3

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

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

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

GrumpyMonkey
источник
Как проверить тип и размер шрифта?
Jé Queue
@ xepoch, это было визуально в тот момент. Причина, по которой он был в стандарте того времени, была двоякой. Менеджеру было легче читать, когда он был распечатан, а шрифт был задан для устранения проблем с пробелами (требовался моноширин), поэтому каждый столбец символов выстроились
GrumpyMonkey
о, боже, - напоминает мне о стандарте, который предписывал количество пустых строк между всем - между методами, которыми я доволен (так как большое количество пробелов помогает различать большие блоки), но до и после каждого блока комментария, и после объявления fn, но до кода функции и т. д ... в конце концов получилось немного глупо.
gbjbaanb
2

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

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

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

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

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

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

TMN
источник
2

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Разное?

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


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

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

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

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

Матье М.
источник
2

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

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

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

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

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

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

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

Конрад Фрикс
источник
Там, где я сейчас работаю, все интерфейсы должны быть реализованы явно, и это большая боль. Если бы только они прочитали Руководящие принципы проектирования платформы, прежде чем писать свой стандарт кодирования.
Мартин Браун
1

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

Рори Олсоп
источник
+1: Это и многопоточность часто неизвестны или неправильно поняты даже опытными разработчиками.
TMN
1

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

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

user281377
источник
1

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

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

оборота бьяркеф
источник
1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

vpit3833
источник
в течение многих лет были кодовые украшения. Google один для вашего языка, вы найдете один.
gbjbaanb
0

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

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

Сэм Фармер
источник
Вы не могли бы объяснить больше о том, что он делает, и почему вы рекомендуете ответить на заданный вопрос? «Ответы только на ссылки» не очень приветствуются на Stack Exchange
gnat
-1

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

aggietech
источник