Руководство для начинающих по написанию комментариев?

27

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

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

Не комментируйте то, что вы делаете, но ПОЧЕМУ вы это делаете.

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

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

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

language-agnostic comments

— Cameron
источник

Я думаю, что мы быстро движемся к миру, где люди больше не комментируют. К лучшему (скорее) к худшему. Agile.

— MK01

1

@ МК: Если это так (я склонен больше соглашаться с этим ответом ), то руководство, объясняющее, как не писать комментарии, и почему их следует избегать, было бы столь же полезным. На самом деле, чем больше разных точек зрения, тем лучше.

— Кэмерон

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

— MK01

см. также: «Комментарии - это запах кода»

— комнат

38

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

Так что не документируйте, ЧТО делает код. Самодокументированный код должен позаботиться об этом. Документ, ПОЧЕМУ вы это делаете. Почему WHY обычно связаны с бизнес-правилами или архитектурой, они не будут часто меняться и так быстро устаревают в WHAT. Чехлы для документов. Исключения документов. Решения по оформлению документов. И самое главное документируйте те проектные решения, которые вы рассматривали, но решили не реализовывать (и документируйте, ПОЧЕМУ вы решили не использовать их)

2

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

— CaffGeek

2

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

— Эрик Гидрик

10

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

— боб
источник

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

— CVn

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

7

Code Complete, как уже упоминалось, имеет различные рекомендации по написанию комментариев. Короче говоря, это PDL, и его можно суммировать как:

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

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

На GameDev.net есть ссылка [которая объясняет PDL] [1], если вы не хотите отслеживать книгу.

— Extrakun
источник

5

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

— Двоичный беспорядок

1

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

— Двоичный беспорядок

1

Не для того, чтобы спорить, а для большего пояснения - псевдокод должен объяснить цель написанного вами кода. Это означает, что комментарий относится не к деталям реализации (таким как «Добавить х в верхнюю часть стека»), а скорее к тому, что должен делать код (например, «Сделать окно появляется поверх всего остального»). Как вы правильно заметили, вам нужно переместить комментарии с кодом. Я не согласен с кодом, может сказать вам, что код делает - все время. Даже если полезный / точный комментарий (если мне удастся написать это хорошо!) Имеет большое значение. В итоге все же ИМХО.

— Extrakun

3

Вызванный метод или функция showWindowOnTop(window)всегда будет лучше, чем комментарий той же природы, все это устарело и плохой совет в 2012 году. 1) Имена функций / методов описывают намерения, 2) псевдокод - пустое упражнение с современными инструментальными цепочками 3) Тесты сообщают вам, что должен делать код, прежде чем писать его, 4) код с хорошим именем лучше, чем комментарии, которые не соответствуют коду с

6

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

— Shahzeb
источник

1

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

— Kevin
источник

1

Ха, да ;-) Это не особенно полезный совет, хотя - возможно, это должен был быть комментарий?

— Кэмерон

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

0

Мне очень нравится, как Эван Тодд суммирует свою точку зрения на единственные полезные категории комментариев ( цитата из его блога ):

Комментарии, объясняющие почему, а не что. Это самые полезные.

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

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

— Cameron
источник