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

142

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

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

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

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

Учитывая все это, возможно ли даже написать хорошие стандарты кодирования, которые отражают эту идею? Те, которые будут релевантными в рецензировании, но не превратятся в бессмысленную контрольную работу, которая производит заметки, не более полезные, чем: «Вы забыли прокомментировать строку 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');
}

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

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

candied_orange
источник
21
Комментарии не для расширенного обсуждения; этот разговор был перенесен в чат .
maple_shaft
32
«Комментарии не для расширенного обсуждения», даже более справедливо для комментариев кода. :) Эти /* Display an error message */комментарии ужасны и фактически влияют на читабельность.
Андреа Лаззаротто
Нам нужны наши IDE, чтобы иметь возможность скрыть комментарии. Может быть, опция как для блочного, так и для встроенного комментария скрывается отдельно. Таким образом, у вас есть лучшее из обоих вариантов. Добавьте много комментариев, но у вас есть возможность скрыть их, чтобы код выглядел чистым и незагроможденным.
Doug.McFarlane
1
@ Doug.McFarlane Я думал, что это должно существовать для vim. Конечно, это происходит как на уровне файлов, так и на уровне блоков - rtfm-sarl.ch/articles/hide-comments.html !
Майкл Даррант
1
Также переключение - stackoverflow.com/a/11842371/631619
Майкл Даррант

Ответы:

171

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

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

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

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

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

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

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

Док Браун
источник
45
Кто это проголосовал? Это ответ для развития критического программного обеспечения. Это другой мир по сравнению с тем, где работает большинство программистов. В этих мирах стандарт кодирования, который требует, чтобы каждая строка кода имела собственный комментарий, не является правильным ответом. Ни один не отказывается от комментариев. OTOH, комментирование при условии проверки кода - это как раз то, что нужно для критически важного программного обеспечения. Это делает код более удобным для просмотра и сопровождения, но это обходится дорого. Эта стоимость меркнет по сравнению с исками на несколько миллионов долларов из-за плохо написанного программного обеспечения.
Дэвид Хаммен
4
мудрый ответ. если бы мы могли найти подлинные правила для кодирования, нам бы не понадобились программисты. мы могли бы просто иметь машинный код. Это могло случиться! :(
4
@DavidHammen: спасибо за ваш комментарий. На самом деле, я думаю, что это относится не только к «критической разработке программного обеспечения». Каждое программное обеспечение, которое поддерживается и развивается в течение многих лет, часто разными людьми, извлечет пользу из понятности для следующего программиста по обслуживанию.
Док Браун
5
Это хороший совет для любого кодирования, а не только для кода, поддерживаемого разными людьми. Даже если вы единственный, кто использует скрипт / программу, в будущем вы, кто должен будет изменить код через год, по достоинству оценят ясность (и время, сэкономленное благодаря отсутствию расшифровки непрозрачного кода).
Энтони Геогеган
5
Не могли бы вы отредактировать «наиболее востребованный ответ» на что-то более объективное? Не каждый читатель узнает историю голосования этих ответов.
candied_orange
151

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

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

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

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

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

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 - есть одно! Так что используйте энергию «стандартов» для стандартов хорошо написанного кода и тестов.

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

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

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

Майкл Даррант
источник
8
Я не верю, что вы ответили на вопрос. Вопрос не в том, чтобы иметь комментарии к каждой строке. Он спрашивает, как сказать разработчикам комментировать код, не заставляя их комментировать каждую строку.
hichris123
7
Да, я не отвечаю на конкретный вопрос о стандартах, но вместо этого пытаюсь помочь людям не идти по этому пути. Так что это, возможно, не ответ на конкретный вопрос, но содержит ценные советы, которые трудно выложить в комментарии.
Майкл Даррант
1
В чем другая сложная проблема?
Дэвид Гринберг
20
@DavidGrinberg аннулирование кеша и отдельные ошибки .
Эрик Кинг
1
Каждой из ваших причин, чтобы избежать комментариев, можно противостоять, но StackExchange не позволяет достаточно длинным комментариям (хех), чтобы я мог обратиться к ним всем здесь. Просто: чрезмерное комментирование похоже на обман избирателей: это случается, но очень редко; когда вы в последний раз видели это? Написание хороших комментариев не должно быть просто запоздалой мыслью; если все сделано правильно, это помогает процессу разработки. Да, это требует ресурсов, но выигрыш - лучший код. Вы никогда не сможете получить такую ​​же отдачу за свой доллар, пожертвовав комментариями ради лучшего стандарта именования переменных. Да, комментировать каждую строку - чокнутый.
kmoser
23

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

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

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

JacquesB
источник
63
Одна из многих вещей, которые я узнал после более чем 40-летнего опыта в этой игре, заключается в том, что здравый смысл вовсе не является общим.
Джон Р. Штром
10
Нет такого понятия, как здравый смысл.
whatsisname
1
in_programming нет .. реальный мир, о, да, но это просто термин для познания реального мира
Майкл Даррант
@ JohnR.Strohm: Мой опыт был гораздо более позитивным, чем ваш, но я также видел, как использование здравого смысла может активно противодействовать механическим принуждению к соблюдению правил.
JacquesB
Я на 99,9% согласен с этим ответом. Стандарт кодирования предназначен для того, на что указывают разработчики, когда в Code Review происходит дискуссия. Проверка кода предназначена для обогащения продукта, а не для начала войн. Так много войн, которые я видел, было спровоцировано Обзорами Кодекса без Стандарта Кодирования. Смею сказать, что если вы не можете автоматизировать проверку элементов в стандарте кодирования, он должен быть там. Обзор Кодекса - это время для передачи «здравого смысла» другим менее опытным разработчикам. Сейчас не время бороться за именование переменных. Линукс / ядро ​​/ gen_init_cpio.c строка 335.
Эндрю Т Финнелл
19

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

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

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

как зовут
источник
1
+1 за «Вы пытаетесь механизировать здравый смысл», -1 за «Ваш единственный вариант - просто надеяться на лучшее», и это оставляет меня без права голоса. Обучение и тренировка вашей команды также возможны. Стандарты могут допускать суждение.
Wildcard
1
@Wildcard Возможно, вы могли бы объяснить, как Стандарт может принимать решения? Разве это не будет Руководство в тот момент? Стандарт - это «идея или вещь, используемая в качестве меры, нормы или модели в сравнительных оценках». Как можно использовать нечто субъективно субъективное, настолько субъективное, в зависимости от того, кто его читает, для измерения качества?
Эндрю Финнелл
1
@Wildcard: проблема в том, что когда вы вступаете в регулируемые отрасли, процесс царит во всем, процесс важнее, чем процесс стоит или нет. Все должно сводиться к флажкам в какой-либо форме, каждый флажок должен быть конкретным и проверяемым, и чем больше у вас флажков, тем больше риск того, что вы столкнетесь с трудностями при аудите.
whatsisname
Это странный мир, и имейте в виду, что правила написаны бюрократами, мало знакомыми с областью программного обеспечения, и вы часто сталкиваетесь с системами, которые существуют для оправдания и требуют себя, а не являются средством для достижения цели обеспечения качества продукции.
whatsisname
1
@whatsisname Я очень рад, что есть кто-то, кто понимает. Ваши ответы написаны более элегантно и точно, чем я когда-либо стремился. Утверждение with systems that exist to justify and require themselves rather than being a means to an end to ensure quality productsименно то, что я пытался проиллюстрировать. Спасибо, что нашли мои слова для меня. Я действительно это имею в виду. Мы должны отделить идею повышения качества от идеи следовать процессу, поскольку они не одинаковы. Вот почему у нас есть QA, Stackoverflow и очень щадящие клиенты.
Эндрю Т Финнелл
14

Обновить

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

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

Проблема здесь в том, что Стандарт кодирования - это просто Стандарт . Чрезвычайно субъективные идеи не должны быть в стандарте кодирования . Это может быть руководство по передовому опыту, но это руководство нельзя использовать против разработчика во время проверки кода. По моему личному мнению, Стандарт Кодирования должен быть как можно ближе к Автоматизированному. В обзорах кода тратится столько времени на обсуждение имен, пробелов, вкладок, скобок, комментариев и т. Д. И т. Д., Когда ВСЕ это можно автоматизировать. Даже ответ о 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, не верь комментариям. Комментарии не ваше решение.

Эндрю Т Финнелл
источник
3
Проблема с комментариями заключается в том, что они НЕ влияют на то, как продукт в конечном итоге работает. хорошо, если человеческая часть чтения и записи кода имеет значение, я думаю, что это влияет на то, как он в конечном итоге работает, но не на то, как код выполняется при окончательной записи, да. Я бы сказал, что проблема с кодом заключается просто в том, что он устарел, а потом хуже, чем отсутствие кода!
Майкл Даррант
1
Здесь, здесь, у нас был хронометрист, который хотел получать ежедневные отчеты о том, что мы делали, чтобы он мог чрезмерно оптимизировать нашу работу. В любом случае мы были немного рассержены тем фактом, что нам приходилось тратить 15 минут каждый день на заполнение его формы, поэтому мы автоматизировали это, заполнив мусор из наших журналов.
joojaa
1
Есть дополнительная проблема с комментарием «Мы не делим на 0, чтобы остановить сбои». Грамматически не ясно, относится ли предложение «для того» к действию деления или его отрицанию. Если вы используете «Мы избегаем деления на 0, чтобы ...», вы избегаете этой двусмысленности. :)
Wildcard
1
«Не делите на ноль, чтобы остановить сбои», на самом деле многое говорит мне о мышлении человека, который его написал. Вы не пишете код, чтобы избежать сбоев! Вы кодируете так, чтобы код был корректным, а не сбои - это лишь малая часть правильности кода. Если вычисление количества
вводимого
1
@AndrewTFinnell Я имею в виду, что если вы иногда получаете ошибку деления на ноль, то добавление «if (divisor == 0) return <нечто>; // избегать деления на ноль» не делает ваш код более корректным. Вместо этого вам нужно выяснить, почему делитель равен нулю, и исправить это. Некоторые алгоритмы разработаны таким образом, что делитель нуля неизбежен, но они являются исключением (и в этом случае вы можете вернуть значение «результат не может быть вычислен»).
immibis
12

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

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

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

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

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

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

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

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

# '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.

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

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

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

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

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

user52889
источник
Документирование публичного API - это хороший момент, но мне действительно нравится объяснять неожиданные решения. Очень хорошо, если нарушение принципа наименьшего удивления сопровождается хотя бы оправданием. +1
candied_orange
1
+1 за посторонние комментарии как шум. Держите сигнал к шуму высоким.
sq33G
+1 особенно для цели комментария побежден, если каждая строка прокомментирована. Жаль, что это может быть (и часто используется) как предлог, чтобы вообще не комментировать, но в любом случае это очень правильно, по причинам, которые вы упомянули плюс, потому что, если каждая строка будет прокомментирована, большинство людей автоматически и по понятным причинам начнут игнорировать все комментарии ,
SantiBailors
10

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

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

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

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

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

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

jmoreno
источник
7
Re Вы не можете кодифицировать стандарт комментирования - Конечно, вы можете. Вы делаете комментарии, подлежащие проверке кода, и этот элемент проверки кода, который говорит, что комментарии не объясняют код, должен быть рассмотрен. Это расходы, которые большинство сред программирования не хотят платить. Это окупается в отношении критического программного обеспечения.
Дэвид Хаммен
«... когда очевидно только, если вы знаете x, y или z» Вы можете указать количество знаний {x, y, z}, которое необходимо знать заранее, чтобы увидеть что-то как очевидное, а затем (вид механически) вы можете проверить, верно ли это для текущего кода. Где нет, добавляйте комментарии, пока это не так.
Триларион
1
@DavidHammen: это не стандарт для комментария, это стандарт для обзора. Именно это я и предложил в качестве решения. Вы не можете сказать, что он должен быть определенного размера, или использовать определенный синтаксис, или даже с пользой требовать комментария в первую очередь (или вы получаете комментарии типа «добавить один к i»). Вы МОЖЕТЕ сказать, что рецензент должен прокомментировать код и комментарии. Как вы говорите, вы можете требовать решения проблем, возникших в результате проверки кода. Но ответственность за это должна была быть на рецензенте, чтобы сделать хорошую работу. Только рецензент может судить, достаточно ли кода и комментария.
Jmoreno
@DavidHammen Люди, выбранные для обзора, делают решение судить? А когда они уходят? Если новые люди не думают так же или говорят по-английски? Если «Рецензенты» уходят? Ваше предложение ставит нескольких разработчиков на вершину Башни Слоновой Кости, что ведет к инакомыслию, недоверию и нарушению коммуникации. Комментарии предназначены для обеспечения понимания или разъяснения для тех, кто может его использовать. Возможно, Джо это нужно, а Мэри нет. Что происходит, когда Мэри рецензент? Или джо? Или Марк?
Эндрю Т Финнелл
@jmoreno - Отсутствие правил / рекомендаций по комментариям в стандартах кодирования означает, что программисты вынуждены искать несколько источников - и они не знают, где искать, пока не вернется обзор, говоря, что комментарии не соответствуют стандартам. Ошибочно думать, что все в стандарте кодирования должно быть автоматизированным. Например, правила для значимых имен не являются автоматическими. По крайней мере, пока. Так , например, x, y, и z, или i, jи kможет быть весьма содержательные имена , если один реализует научный алгоритм , основанный на журнальной бумаги, используемой именно эти имена в своих формулах.
Дэвид Хаммен
9

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

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

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

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

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

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

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

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

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

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

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

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

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

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

luk32
источник
2
Использование обзоров кода для определения имен переменных, классов и методов - лучший способ заставить людей ненавидеть компанию, бизнес или методологию. Обзоры кода не должны использоваться как способ принуждения к вещам, которые действительно не имеют значения. Стандарт кодирования должен проверяться с помощью автоматизированного процесса. Переменная длина имени, круговая сложность, закон Деметры - все это можно проверить. Если бы кто-то сказал мне переименовать переменную из 'i' во что-то вроде indexForThePreviousCollection, я бы нашел другое место для работы. Переменные> 3 символа проверяются перед регистрацией автоматически.
Эндрю Финнелл
3
@AndrewTFinnell Я могу написать невозможно следовать коду в любой парадигме программирования, которую вы хотите назвать.
candied_orange
2
@AndrewTFinnell Хорошо, я буду вежливо не согласен. « Использование проверок кода для диктовки », я не знаю, откуда вы это взяли. Я не хотел бы работать над кодом с переменными i, j, kповсюду после того , как оригинальный автор завершает работу. Я не понимаю вашу точку зрения на "человеческий" геном. Я сомневаюсь, что есть язык, где одно утверждение или два слишком сложны для понимания. Как я уже сказал, я видел сложные ifs и LINQоднострочники. Они могут быть либо прокомментированы, либо реорганизованы под семантически значимым именем, я думаю, это ваш «хороший комментарий».
luk32
3
@ luk32 Я уважаю право не соглашаться. Итерационные переменные вполне очевидны с моей точки зрения. Хотя я понимаю смысл вашего заявления, я считаю, что существует слишком много практик, которые доводят это чувство до крайности. Нам действительно нужен код, который читает: for (int indexForCurrentDatabaseRow = 0; indexForCurrentDatabaseRow < currentUserRecordSetResults.length; indexForCurrentDatabaseRow = indexForCurrentDatabaseRow + 1)против for (int i = 0; i < results.length; i++)? Возможно, это вопрос предпочтений и / или времени, потраченного на просмотр кода. Чрезмерно многословные имена пахнут для меня.
Эндрю Т Финнелл
2
Я не думаю, что имена должны быть решены в обзорах кода. Обзор кода обычно начинается после того, как автор считает, что он достаточно хорош, что также означает, что он правильно прокомментирован, прост для понимания и переменные имеют приличные имена. Дело в том, что если рецензенты думают, что код слишком сложен или борются со значением переменной, то этот код трудно понять. Это не подлежит обсуждению - очевидно, по крайней мере один разработчик - рецензент - не понял этого. Должен ли он быть подвергнут рефакторингу (и как) или должным образом прокомментирован - это другой вопрос.
Идан Арье
9

Вопрос:

Учитывая все это, возможно ли даже написать хорошие стандарты кодирования, которые отражают эту идею? Те, которые будут иметь отношение к рецензированию, но не превратятся в бессмысленную контрольную работу, которая будет производить заметки, не более полезные, чем: «Вы забыли прокомментировать строку 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 демонстрируют хороший стандарт кодирования, который отражает эту идею. Так что да, я верю, что это возможно.

Аарон Холл
источник
1
«Предполагается, что читатель знает язык лучше, чем писатель». Мне трудно поверить, что это правильное отношение. Я могу видеть, предполагая, что они знают так много , но каждая команда различна, и каждый человек в команде различен, поэтому общее утверждение по этому конкретному вопросу не кажется мудрым.
Брайан Оукли
4
Без этого руководства младшие программисты будут комментировать комментарии, объясняющие тривиальный код, только самим себе, а программисты среднего уровня, использующие неудобные решения, просто делают код более доступным для начинающих программистов. Это руководство устраняет избыточность и гарантирует, что даже опытный программист продолжает совершенствовать свой код. Когда я сам возвращаюсь к коду, я могу забыть контекст, но в целом я знаю, что делает язык, даже лучше, чем когда я его впервые писал.
Аарон Холл
4

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

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

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

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

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

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

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

Ewan
источник
6
За 20 лет я никогда не видел, чтобы кто-то комментировал прототип их кода таким образом, а затем заполнял пробелы реальным кодом. Уже есть объективный способ добиться того, что вы говорите, или того, что, я думаю, вы говорите. Это называется Test Driven Development. Модульные тесты определяют спецификацию и соответствует ли код этой спецификации. Все без комментариев.
Эндрю Т Финнелл
9
Хотя я не думаю, что код в вопросе является хорошим примером этого, практика написания процедуры сначала в комментариях, а затем возврата и заполнения кода специально вызывается в «Code Complete» как единое целое. возможная практика, чтобы помочь создать читаемый код, @AndrewTFinnell. Это точно не неслыханно, даже если это вне вашего опыта.
Джош Касвелл
6
также предшествует TDD, я верю
Ewan
2
Вы говорите о процессе программирования псевдокода? Целью этого было уменьшить количество комментариев. Я никогда не помню, чтобы эту книгу с комментариями нужно было оставить в коде. А комментирование для создания концептуальной процедуры подразумевает высокий уровень, а не низкий уровень. Если бы нужно было прокомментировать каждую строку, которую они намеревались написать, они могли бы просто написать строки. Идея состоит в том, чтобы прототипировать принципы кода, а не каждую строку. Книга не предлагает комментировать каждую строку. Это фокус этого вопроса. И я могу ошибаться, но я верю, что это во втором издании.
Эндрю Т Финнелл
2
@JoshCaswell & Ewan, да, это была техника много лет назад и действительно предшествовала TDD. Но вы должны были удалить комментарии позже! И TDD полностью вытеснил его как разумный способ создания кода, который соответствует спецификации.
Дэвид Арно
4

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

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

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

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

Джон Боде
источник
Очевидное в глазах смотрящего. И меняется в зависимости от срока.
Тони Эннис
3

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

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

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

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

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

Идан Арье
источник
1
Пропустите важные комментарии: +1. Предложение, которое начинается: «Они не описывают», может использовать некоторую реструктуризацию, чтобы было легче следовать.
candied_orange
3

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

  i++;    /* Increment i */

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

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

jamesqf
источник
2
+1 к комментарию doxygen: это именно мое возражение против включения документирования doxygen в мой код; 95% времени это просто повторяет то, что уже очевидно из сигнатуры функции. Я тоже еще не видел ни одной документации по доксигену, которая бы чего-то стоила. Написание этих комментариев тратит время три раза: один раз, чтобы написать комментарии, один раз, чтобы прочитать их снова, и один раз, чтобы отладить проблемы, вызванные устаревшим содержанием комментариев.
Мастер
1
Ты не противоречишь себе? Я думаю, что мы оба согласились бы, что для функции важно иметь комментарий, описывающий то, что она делает с точки зрения черного ящика - «эти входные данные входят, функция делает это, и эти выходные результаты выходят». Он формирует договор между человеком, который написал функцию, и людьми, которые используют функцию. Цель Doxygen - просто стандартизировать формат этих комментариев таким образом, чтобы их можно было проанализировать и сделать доступными для поиска / индексации. Так зачем вам нужен «хороший блок комментариев», а не в стандартном, читаемом человеком и машиночитаемом формате?
Грэм
По словам @Graham, использование стандарта комментариев, такого как JSDoc, JavaDoc и Doxygen, предназначено для предоставления доступной для поиска и удобочитаемой документации. Строка кода, упомянутая в этом ответе, не имеет ничего общего с Doxygen. Я даже не могу представить, чтобы существовал набор правил, который бы анализировал этот комментарий и создавал запись в выводимой документации. Когда вы смотрите на Документы для JMI, Стандартные библиотеки Java и т. Д., Все они создаются с использованием инструмента, очень похожего на Doxygen. Это цель этого. Не то, что здесь сказано
Эндрю Т Финнелл
Я не придумываю это - чтобы удовлетворить канадское требование, компания, в которой я работал, заставила разработчиков написать предварительный процессор, который добавил комментарии ТОЧНО, как пример OP. Я думаю, что наш был "C ADD 1 TO I" или что-то подобное. Это был Фортран, поэтому петли были так же рекомендованы "C LOOP FROM 1 - 10". Код был загружен с бесполезными комментариями. Я удалил всю эту ерунду, когда поддерживал код. Никто никогда не говорил мне ничего.
Тони Эннис
2

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

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

hildred
источник
Мне жаль сообщать вам, что блок-схемы никогда не исчезали.
Муравей P
Хорошие комментарии находятся на другом уровне абстракции, чем код . Слышу, слышу!
Candied_Orange
1
Хотя это может быть неплохим советом, похоже, он не затрагивает вопрос, который был задан, за исключением, возможно, одного предложения.
Брайан Оукли
0

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

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

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

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

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

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

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

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

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

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

DVK
источник
0

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

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

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

BЈовић
источник
1
Но «документация», создаваемая такими инструментами, по крайней мере, по моему опыту, вообще стоит меньше, чем вообще никакой документации, потому что она не предоставляет пользователю полезной информации (и заставляет его тратить время на извлечение ненужной информации). существующей информации), но вводит разработчиков в заблуждение, что они правильно документировали свой код.
jamesqf
@jamesqf Да, когда половина функций не документирована, а другая половина плохо. Однако doxygen может генерировать довольно хорошую документацию, предполагая, что разработчики правильно прокомментировали свои функции, классы и т. Д.
BЈовић
-1

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

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

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

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

Эрдрик Айронроуз
источник