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

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

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

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

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

Учитывая все это, возможно ли даже написать хорошие стандарты кодирования, которые отражают эту идею? Те, которые будут релевантными в рецензировании, но не превратятся в бессмысленную контрольную работу, которая производит заметки, не более полезные, чем: «Вы забыли прокомментировать строку 42».

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

/* Display an error message */
function display_error_message( $error_message )
{
    /* Display the error message */
    echo $error_message;

    /* Exit the application */
    exit();
}

/* -------------------------------------------------------------------- */

/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
    /* Display an error message */
    display_error_message( 'Error: Configuration file not found. Application has stopped');
}

Если это возможно правильно выразить в стандартном документе, а это может быть просто невозможно, я бы хотел изложить идею по этому принципу:

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

Ответ Майкла Дарранта - ИМХО неплохой, но он не дает буквального ответа на вопрос (как он сам признал), поэтому я постараюсь дать ответ, который дает:

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

Учитывая все это, возможно ли даже написать хорошие стандарты кодирования, которые отражают эту идею?

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

• «Если есть комментарий, объясняет ли он, почему код делает то, что делает?»
• «Является ли каждая строка кода - в своем контексте - достаточно понятной, чтобы не нуждаться в комментариях, или, если нет, сопровождается ли она комментарием, который закрывает этот пробел? Или (предпочтительно) код может быть изменен так ему больше не нужны комментарии?

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

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

Основные анти-паттерны, приводящие к некачественному коду с меньшей четкостью

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

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

Разработчики будут склонны писать худший код. Они будут использовать более загадочные имена и структуры, потому что «это объяснено в комментарии - смотрите!».

Рассмотреть возможность:

living_room_set = tables + chairs.

Теперь рассмотрим:

set = tbls+chrs # Make the set equal to the table plus the chairs

У вас есть не только более загадочные имена и больше, чтобы прочитать, вы также должны смотреть назад и вперед, смотреть на код, что такое набор? посмотрите на код слева, посмотрите на комментарии, что такое tbls, посмотрите на код слева, посмотрите на комментарии, что такое chrs, посмотрите на комментарий. Yuch!

Резюме

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

• Код и Комментарии не синхронизируются друг с другом, когда изменяется только один

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

• Код становится все труднее читать

• Хороший код становится труднее писать

• Склонность использовать более загадочные имена

• Чрезмерные символы для чтения в коде и комментариях

• Разные редакторы используют разные стили

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

• Отнимает время и ресурсы и вычитает из долгосрочной стоимости *

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

Одна из двух трудных проблем - это называть вещи - не пропустите проблему с комментариями.

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

* код завтрашнего дня

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

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

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

Это невозможно. То, что вы по сути пытаетесь сделать, это почти механизировать здравый смысл.

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

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

Обновить

Мой ответ в цитатах для акцента:

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

Проблема здесь в том, что Стандарт кодирования - это просто Стандарт . Чрезвычайно субъективные идеи не должны быть в стандарте кодирования . Это может быть руководство по передовому опыту, но это руководство нельзя использовать против разработчика во время проверки кода. По моему личному мнению, Стандарт Кодирования должен быть как можно ближе к Автоматизированному. В обзорах кода тратится столько времени на обсуждение имен, пробелов, вкладок, скобок, комментариев и т. Д. И т. Д., Когда ВСЕ это можно автоматизировать. Даже ответ о tablesи chairsможет быть автоматизирован. LINT'ers позволяют использовать словари, проверки на заглавные буквы в зависимости от концепции (переменная, функция, метод, класс и т. Д.).

Даже проверка JavaDoc может быть осуществлена ​​роботом LINT'er до принятия запроса на извлечение. Многие Open Source проекты делают именно это. Вы отправляете запрос на извлечение, код строится из файла Travis-CI, включая статический анализ, и он должен пройти все стандарты кодирования, которые могут быть объективно выражены. Никто не говорит о том, что «делать это неправильно» или «не предоставлять значение» с комментариями, или о неправильном способе именования переменных, и др. Эти обсуждения не приносят никакой пользы, и их лучше оставить стороннему роботу, который может взять на себя всю тяжесть нашего эмоционального кодирования.

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

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

Как это может когда-либо быть должным образом выражено в каком-либо стандарте? Стандарт бесполезен, если его нельзя применять последовательно и справедливо, где справедливость больше касается объективности, а не эмоций.

Я оспариваю, что Стандарт кодирования должен оставаться максимально объективным. То, как переменные называются IS цель. Их можно легко проверить по словарю на предмет правильного написания, грамматической структуры и корпуса. Все, кроме этого, является «спичкой», которую выигрывает человек с наибольшей силой или «бьющий лоб». Что-то я лично борюсь с НЕ делаю.

Когда я комментирую, я всегда комментирую разговор с моим будущим я в третьем лице. Если я вернусь к этому коду через 5 лет, что мне нужно знать? Что было бы полезно, что могло бы сбить с толку, и что было бы устаревшим с кодом? Существует различие между документированием кода для генерации общедоступного API с возможностью поиска и комментарием, который предоставляет ценность неизвестной третьей стороне, даже если эта третья сторона принадлежит вам.

Вот хороший лакмусовый тест. Если бы вы были ЕДИНСТВЕННЫМ в проекте. Вы знали, что будете единственным в проекте. Что будет в вашем стандарте кодирования? Вы хотите, чтобы ваш код был чистым, понятным и понятным для себя в будущем. Хотели бы вы иметь обзор кода с собой о том, почему вы не поместили комментарий в каждой строке? Будете ли вы просматривать каждый комментарий, который вы создали для 100 файлов, которые вы зарегистрировали? Если нет, то зачем заставлять других?

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

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

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

У нас есть два типа комментариев:

Машиносчитываемые комментарии

Стили комментариев, такие как Javadoc, JSDoc, Doxygen и т. Д., - все это способы комментирования открытого интерфейса, предоставляемого набором кода. Этот интерфейс может использоваться только одним другим разработчиком (проприетарный код для команды из двух человек), неизвестным числом разработчиков (например, JMS) или для всего отдела. Этот код может быть прочитан автоматизированным процессом, который затем производит другой способ чтения этих комментариев, например HTML, PDF и тому подобное.

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

Я делаю то, что выглядит сумасшедшим, но на самом деле это не

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

Этот тип кода является причиной многих проблем. Обычно он не комментируется, а позже обнаруживается новым разработчиком и исправляется. Таким образом, ломая все. Даже тогда, комментарии только там, чтобы объяснить ПОЧЕМУ, чтобы фактически не препятствовать чему-либо сломаться.

На комментарии нельзя положиться

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

Это может звучать глупо, но терпите меня. Какая из этих двух строк действительно имеет значение?

// We don't divide by 0 in order to stop crashes.

return 1 / n;

В этом примере все, что имеет значение, - это то, что мы понятия не имеем, что такое «n», нет проверки на то, что n равно 0, и даже если бы оно было, ничто не мешает разработчику n = 0ПОСЛЕ проверки после 0. После этого комментарий бесполезен, и ничто автоматизированное не может поймать это. Никакой стандарт не может это поймать. Комментарий, хотя довольно (для некоторых) не имеет никакого отношения к результату продукта.

Разработка через тестирование

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

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

Документация хороша, когда вы пытаетесь понять, ПОЧЕМУ кто-то сделал что-то определенным образом, однако, я обнаружил, что за эти годы документация обычно используется для объяснения, почему было сделано что-то «умное», когда это действительно не нужно быть написанным таким образом.

Заключение

Если вы работаете в компании, которой ТРЕБУЕТСЯ комментировать каждую строку, Я ГАРАНТИРУЮ, по крайней мере, два программиста проекта уже написали программу автоматического документирования на Perl, Lisp или Python, которая определяет общее представление о том, что делает строка. , а затем добавляет комментарий над этой строкой. Поскольку это возможно, это означает, что комментарии бесполезны. Найдите инженеров, которые написали эти сценарии для автоматического документирования кода, и используйте их в качестве доказательства того, почему «Комментарий к каждой строке» тратит время, не приносит никакой пользы и потенциально причиняет вред.

Кроме того, я помогал близкому другу с заданием по программированию. Его учитель поставил требование, чтобы каждая строка была документирована. Так что я вижу, откуда взялся этот мыслительный процесс. Просто спросите себя, что вы пытаетесь сделать, и это правильно? Тогда спросите себя; Есть ли способ «сыграть» систему с этим процессом? Если есть, то действительно ли это добавляет ценность? Нельзя автоматически писать модульные тесты, которые проверяют, что код соответствует определенной спецификации, и если бы они могли, это не было бы плохо.

Если устройство должно работать в определенных условиях, потому что оно будет находиться внутри человека, единственный способ гарантировать, что оно не убьет их, - это годы испытаний, экспертных проверок, испытаний, а затем НИКОГДА не изменяйте код снова. Вот почему НАСА до сих пор использует такое старое оборудование и программное обеспечение. Когда дело доходит до жизни или смерти, вы не просто «вносите небольшие изменения и регистрируете это».

Комментарии не имеют никакого отношения к спасению жизней. Комментарии для людей, люди делают ошибки, даже когда пишут комментарии. Не верь людям. Ergo, не верь комментариям. Комментарии не ваше решение.

Есть две разные вещи, на которые вы ссылаетесь, когда говорите о комментариях. Они не одинаковы, и различие важно.

Документация рассказывает о битах фрагмента кода, обращенных наружу, - о его интерфейсе.

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

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

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

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

Комментарии всегда читаются среди основного кода.

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

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

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

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

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

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

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

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

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

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

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

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

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

Комментировать каждую строку кода? Нет .

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

Комментарии к читаемому коду в лучшем случае излишни, а в худшем - отбросят читателя в поисках несуществующей цели комментария.

Если вы комментируете весь код, который говорит само за себя, вы удваиваете объем чтения без предоставления какой-либо дополнительной информации. Я не уверен, что такая избыточность окупится. Можно представить себе рецензента, который говорит, что 42 говорит « display_error», а в комментарии «отображается предупреждение». Но представьте себе изменение в коде. У вас есть два места, чтобы исправить сейчас. Становится ясно, что у этого стиля есть негативы копирования-вставки.

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

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

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

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

(Лично я не фанат строгого правила отсутствия комментариев, но я считаю, что это хорошее начальное мышление.)

Учитывая все это, возможно ли даже написать хорошие стандарты кодирования, которые отражают эту идею?

Что касается процесса. Наш стандарт дал довольно много рецензента. Предполагая, что они не являются вредоносными, это работает хорошо.

Когда он спрашивает «Что такое переменная o?», Вы переименовываете его. Если он спрашивает, что делает этот блок, либо рефакторинг, либо комментарий. Если были дебаты о том, ясно ли что-то или нет, если рецензент не получил это, то по определению это не так. В очень редких случаях было что-то вроде второго мнения от нескольких друзей.

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

Также не было абсолютов . Хотя мы были небольшой группой. В группе из 5 легко найти консенсус.

Вопрос:

Учитывая все это, возможно ли даже написать хорошие стандарты кодирования, которые отражают эту идею? Те, которые будут иметь отношение к рецензированию, но не превратятся в бессмысленную контрольную работу, которая будет производить заметки, не более полезные, чем: «Вы забыли прокомментировать строку 42».

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

Читатель этого кода, из вашего примера, должен знать, что exit()выйдет из приложения - таким образом делая комментарий излишним:

/* Exit the application */
exit();

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

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

PEP 8 Python (руководство по стилю для Python в стандартной библиотеке CPython) содержит следующие рекомендации для встроенных комментариев:

Используйте встроенные комментарии экономно.

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

Встроенные комментарии не нужны и фактически отвлекают, если они утверждают очевидное. Не делай этого:

x = x + 1                 # Increment x

Но иногда это полезно:

x = x + 1                 # Compensate for border

Учитывая такой пример, я лично предпочитаю пойти дальше и постараюсь также исключить этот комментарий. Например, я мог бы прийти к:

border_compensation = 1
compensated_x = x + border_compensation

Создание самодокументируемого кода - не новая идея .

Вернуться к актуальному вопросу:

Учитывая все это, возможно ли даже написать хорошие стандарты кодирования, которые отражают эту идею?

Я считаю, что руководство и пример PEP 8 демонстрируют хороший стандарт кодирования, который отражает эту идею. Так что да, я верю, что это возможно.

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

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

редактировать ----

Просто для ясности. Я не получаю в комментарии против тдд против модульных тестов, которые лучше. Или предлагать комментарий к строке - это хорошо / плохо

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

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

то есть комментарии для объяснения цели кода, который также является спецификацией

Учитывая все это, возможно ли даже написать хорошие стандарты кодирования, которые отражают эту идею? Те, которые будут иметь отношение к рецензированию, но не превратятся в бессмысленную контрольную работу, которая будет производить заметки, не более полезные, чем: «Вы забыли прокомментировать строку 42».

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

Мое правило № 1 - «Не документируйте очевидное». Правило № 2 - «Напиши очевидный код».

Для критически важного кода (над которым мне никогда не приходилось работать, слава Богу), это необходимый, но далеко не достаточный первый шаг. Возможно, даже придется сводиться к тому, чтобы указывать, каких языковых функций следует избегать (я видел более одного стандартного указания: «Не используйте scanf( "%s", input ); по какой-либо причине »).

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

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

Таким образом, вы не должны комментировать строки - вы должны комментировать фрагменты кода. Конкретные комментарии могут быть размещены рядом со строками, на которые они ссылаются, но эти комментарии по-прежнему относятся к большему коду. Они не описывают, что / почему строка делает - они описывают, что она делает в этом коде и / или зачем это нужно в этом коде.

Таким образом, следует комментировать не строки, а большие куски кода. Нужно ли комментировать каждый фрагмент кода? Нет. Гарольд Абельсон сказал, что « Программы должны быть написаны для того, чтобы люди могли читать, и только для того, чтобы машины выполнялись ». Но комментарии только для людей, чтобы читать - машина не выполняет их. Если ваши стандарты кодирования вынуждают писать избыточные комментарии к каждой строке / куску кода, вы не просто обременяете разработчика, который должен их писать, - вы также обременяете разработчиков, которым придется их читать !

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

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

  i++;    /* Increment i */

абсолютно без понятия о том, почему вы хотите увеличить i. Расширим это немного, и вы получите типичный стиль комментариев Doxygen, который дает много словоблудия, не давая никакого представления о том, для чего предназначен код или как он работает. (По крайней мере, насколько я когда-либо видел: я допускаю, что можно было бы написать полезную документацию, используя такую ​​систему, но я не затаил дыхание.)

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

Пришло время вернуть блок-схемы! (не совсем, но подожди минутку)

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

Я отвечу на вопрос, как указано:

Учитывая все это, возможно ли даже написать хорошие стандарты кодирования, которые отражают эту идею?

Да. WYSIWYG. Хороший стандарт кодирования буквально « понятен читателю, что делает следующий код и почему ».

Другими словами, мои комментарии к коду о читабельности кода буквально, 1-1, возникают из моего психического состояния

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

Как правило, людям легко понять, что «это требует большей читабельности», когда они слышат: «Я, как старший разработчик, которого, как мы надеемся, вы уважаете, как не глупый, сначала не читал, понял этот код или почему он там или что он делает, так что это нужно объяснить ".

Это смещает дискурс с «вы не следовали бессмысленным стандартам» на «ваш код имеет определенный недостаток читабельности, приводящий к практическим проблемам ».

Вторым стандартом, который необходимо сделать явным, является «Аварийное испытание в 2 часа ночи».

Может ли ваша резервная копия, не имеющая опыта работы с этим кодом, выяснить, в чем заключается проблема с кодом при его отладке во время производственного аварийного моста в 2 часа ночи, когда вы находитесь в отпуске в чилийских Андах без мобильного телефона?

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

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

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

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

Многие из существующих ответов очень подробны, но я чувствовал, что важно ответить:

... [комментарии], которые будут актуальны в экспертной оценке, но не превратятся в бессмысленную контрольную работу ...

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

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