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

В то время как я читал этот вопрос , самый популярный ответ цитировал дядю Боба по стандартам кодирования , но я был смущен этим советом:

3. Не записывайте их, если можете этого избежать. Скорее пусть код будет способом, которым стандарты собраны.

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

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

Есть несколько причин.

1. Никто не читает документацию.
2. Никто не следует документации, даже если они читают ее.
3. Никто не обновляет документацию, даже если они читают ее и следуют ей.
4. Написание списка практик гораздо менее эффективно, чем создание культуры.

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

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

Есть другая интерпретация. Я не верю, что это имел в виду дядя Боб, но это стоит рассмотреть.

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

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

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

Если это имеет значение, то определите строго, что именно вы хотите, и потерпите неудачу, если это не так.

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

Большинство решений в стандарте кодирования будут иметь очень незначительное влияние на удобочитаемость и производительность. Особенно, если вы принимаете «нормальный» стиль для языка, и разработчики языка начинают понимать, что это должно быть частью спецификации (например, Go).

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

Наличие письменного стандарта заканчивает спор. Менеджеры могут указывать на это и отражать недовольство документом. Вы можете поспорить с листком бумаги, но он вас не послушает.

(См. Также Тирания бесструктурности )

Потому что комментарии это ложь .

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

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

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

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

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

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

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

Почему я не должен записывать Стандарт кодирования?

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

НАПИШИТЕ ЭТО ВНИЗ . Однако я постараюсь объяснить мои причины ...

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

Однако формулировка дяди Боба не заставляет меня думать, что он говорит об этом.

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

• В некоторых случаях письменные стандарты кодирования требуются по закону.
• Я читаю документацию и уверен, что я не одинок. Члены команды могут со временем меняться, знания не могут быть в 5-10-летней базе кода или в головах членов команды. Организации должны увольнять людей, которые не следуют внутренним правилам.
• Стандарты кодирования, как только они будут утверждены , не будут часто меняться, и если они это сделают, вы хотите знать об этом. Если стандарты изменились, то ваша документация (в коде) устарела, потому что весь ваш код не соответствует новому стандарту. Переформатирование / рефакторинг может быть медленным, но у вас всегда есть письменное авторитетное руководство.
• Лучше прочитать 5-страничный документ, чем проверять 10 / 20K LOC, чтобы экстраполировать правило (которое вы можете неправильно понять, кстати), без сомнения об этом.
• Ирония в том, что кто-то, кто написал много книг о принципах дизайна и стиле кодирования, предлагает вам не писать свои собственные правила, разве не лучше, если он бросит нас с некоторыми примерами кода? Нет, потому что в письменных руководствах говорится не только о том, что делать, но и о двух других вещах, которых не хватает в коде: что не следует делать и причины делать это или нет.

«Свободное самоорганизующееся программирование» хорошо для 16-летнего парня-ниндзя, но у организаций есть другие требования :

• Качество кода должно быть предоставлено (и определено) на уровне компании - это не то, что может решить одна команда. Они могут даже не иметь навыков, чтобы решить, что лучше (например, сколько разработчиков имеют все необходимые навыки для проверки MISRA или даже просто понимают каждое правило?)
• Участники могут перемещаться в разные команды: если все придерживаются одних и тех же стандартов кодирования, интеграция проходит гладко и менее подвержена ошибкам.
• Если команда самоорганизуется, то со временем, когда члены команды меняются, стандарты будут развиваться - и тогда у вас будет огромная база кода, которая не соответствует действующим принятым стандартам .

Если вы думаете о людях до процесса, я могу только предложить прочитать о TPS: люди являются центральной частью Lean, но процедуры очень формализованы.

Конечно, небольшая организация, в которой есть только одна команда, может позволить команде решить, какие стандарты следует принять, но затем она должна быть записана. Здесь, на Programmers.SE, вы можете прочитать посты Эрика Липперта: я полагаю, мы все согласны с тем, что он опытный разработчик, когда он работал в Microsoft, ему приходилось придерживаться их письменных рекомендаций (даже если некоторые правила могут быть неправильными , неприменимыми или бесполезными). ему.) Как насчет Джона Скита? Правила Google довольно строгие (и многие люди с ними не согласны), но он должен придерживаться таких правил. Это неуважительно к ним? Нет, они, вероятно, работали над определением и улучшением таких рекомендаций, компания не состоит из одного члена (или одной команды), и каждая команда не является островом .

Примеры

• Вы решили не использовать множественное наследование и вложенные классы в C ++, потому что вы, члены команды , плохо понимаете это . Позже кто-то, желающий использовать множественное наследование, должен просмотреть весь 1M LOC, чтобы увидеть, использовалось ли оно когда-либо. Это плохо, потому что если проектные решения не задокументированы, вам нужно изучить всю кодовую базу, чтобы понять их. И даже тогда, если он не использовался, это потому, что он противоречит стандарту кодирования или это разрешено, но просто не было более ранних ситуаций, когда множественное наследование подходило?
• В C # у вас были перегруженные методы для предоставления параметров по умолчанию, потому что ваша кодовая база началась, когда дополнительные параметры были недоступны в C #. Затем вы изменили и начали использовать их (рефакторинг старого кода, чтобы использовать их каждый раз, когда вам приходилось изменять такие функции). Еще позже вы решили, что необязательные параметры являются плохими, и вы начали избегать их использования. Какое правило ваш код говорит вам? Это плохо, потому что стандарт развивается, но кодовая база развивается медленнее, и если это ваша документация, то у вас проблемы.
• Джон перешел из команды А в команду Б. Джон должен выучить новый стандарт; во время обучения он, вероятно, представит более тонкие ошибки (или, если повезет, просто займет много времени, чтобы понять существующий код и сделать проверку кода более длительной).
• Команда A переходит на кодовую базу, ранее принадлежавшую команде B. У нее совершенно другие стандарты кодирования. Переписать? Адаптировать? Смешать? Все они одинаково плохи.

Дядя боб

Пусть они развиваются в течение первых нескольких итераций.

Правда, до тех пор, пока у вас нет стандарта и ваша организация не поставит вам задачу его создать .

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

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

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

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

Не издавайте закон о хорошем дизайне. (например, не говорите людям не использовать goto)

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

Убедитесь, что все знают, что стандарт касается общения, и ничего больше.

Мало того, что хороший стандарт касается качества, если вы не хотите иметь стандарт только для мелких деталей.

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

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

Три ноты:

• На мой взгляд, недостатки в некоторых языках более серьезны, чем в других, например, в C ++ стандарт уровня компании еще более необходим, чем в Java.
• Это рассуждение может не применяться полностью (а причины дяди Боба могут быть менее экстремальными ), если вы работаете в очень маленькой компании, где у вас всего одна небольшая команда.
• Вы наняты (как команда), и вы будете работать в одиночку с одним новым проектом, тогда вы забудете его и продолжите. В этом случае вам может быть все равно (но ваш работодатель должен ...)

1. Чтобы быть полезным, стандарт кодирования не должен говорить о вопросах существа; только вопросы стиля. Следует указывать только те вещи, которые являются произвольными и неоднозначными. например, расположение фигурных скобок, глубина отступа, пробелы и табуляции, соглашения об именах и т. д.
2. Проблемы стиля являются локальными, а не глобальными. Каждая команда должна принять свой особый стиль, соответствующий их задачам и их индивидуальности. Это делает стандарты простыми и легкими. Корпоративные стандарты перегружены всеми возможными соображениями, конфигурациями и исключениями.
3. Внутри команды единственной причиной написания отдельного документа стиля кодирования является то, что код, созданный командой, не соответствует стандарту. В этом случае у вас нет стандарта. Чтобы быть эффективным, стандарт должен быть выражен самим кодом. И если это так, то нет необходимости в отдельном документе.
4. В устаревших системах команды и стили меняются со временем. В этом нет ничего плохого. Старый код будет иметь более старый стиль. Более новый код будет иметь более новый стиль. Команда должна знать о стилях и их возрасте. Всякий раз, когда пишется новый код, он должен быть в новом стиле, независимо от того, где он находится в коде.

Почему я не должен записывать Стандарт кодирования?

Существует много причин для этого. Вот некоторые соображения:

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

2. Когда проект будет отложен / отложен / и т.д. тогда те немногие люди, которые остаются, обычно не могут придерживаться (или, возможно, даже не читали) стандартов. Следующее, что вы знаете, все эти усилия по «поддержанию кода в чистоте» в любом случае были потрачены впустую.

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

Вы должны обязательно прочитать # 6:

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

Другими словами, когда пришло время начать проект, просто попробуйте какое-то время. Затем обсудите общие правила стандартов кодирования, которые использует текущая команда, и в основном следуйте им. Таким образом, вы максимизируете усилия по улучшению продукта, одновременно сводя к минимуму усилия, необходимые для написания, просмотра и документирования «синтаксического сахара», необходимого для получения исполняемого кода.

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

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

Во-первых, насколько я знаю, дядя Боб - человек Java, это очень важно для понимания того, что он говорит.

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

Java и C #, как и большинство современных языков, были определены так, чтобы у программиста было немного «простых» ловушек.

Однако когда я начал программировать, я использовал C (а позже C ++). В C вы можете написать код, как

if (a = 3);
{
   /* spend a long time debugging this */
}

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

if (3 = a)
{
   /* looks odd, but makes sense */
}

Компилятор выдает ошибку, и я легко изменить код на 3 == a. Аналогично, если стандарт кодирования не позволяет= использовать его внутри ifусловия или «пустого ifоператора», то для отслеживания этой ошибки можно использовать средство проверки кода как часть системы сборки.

Мои взгляды на стандарты кодирования сильно изменились, когда я отошел от C / C ++: раньше мне нравились стандарты кодирования, которые строго соблюдались, и много страниц. Теперь я думаю, что вам нужно всего лишь перечислить используемые инструменты и получить неофициальное соглашение между первоначальными членами команды по нескольким соглашениям об именах. Мы больше не живем в мире команд из более чем 30 разработчиков, пишущих приложения на C / C ++ ...

Есть причина, по которой мне никогда не нравился JScript, и я думаю, что TypeScript - это лучшее, что может случиться с веб-разработкой за многие годы. Я ожидаю, что разработчикам веб-интерфейса все еще нужны стандарты кодирования из-за дефектов в дизайне HTML / CSS / JScript и т. Д.

Наличие источника в качестве стандарта самодокументируемого кодирования подразумевает две вещи.

1. Люди должны обращаться к базе кода и просматривать ее, чтобы стать опытными участниками. Это невероятно важно. Чтение руководств по кодированию - это пустая трата времени по сравнению с изучением основ кода.
2. Он признает, что незначительные различия не важны. Важно договориться и понять основные принципы. Поддержание единого стиля не преследуется как искусство для искусства. Это не позволяет нетворческим придиркам раздражать и отвлекать других людей. Речь идет об облегчении общения через код в команде.

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

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

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

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

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

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

Сильно связаны: Эволюция в стандартах кодирования, как вы справляетесь с ними?

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

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

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

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

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

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

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

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

Но это относится к кодированию , а не к стилю .

Изобретатели C и C ++ показывают, например, использование строчных имен, а не CaMelCaSe. Так почему же многие разработчики не следуют неявному примеру из фонда? Разве стиль стандартной библиотеки и канонических учебных материалов не должен быть подходящим для подражания?

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

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