Каковы преимущества использования комментариев?

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

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

6 голосов | спросил AngryBird 15 thEurope/Moscowp30Europe/Moscow09bEurope/MoscowThu, 15 Sep 2011 01:05:13 +0400 2011, 01:05:13

8 ответов


15

Clean Code содержит целую главу о комментариях, когда они хороши, а когда нет. Также много практических советов о том, как писать код, которому не нужно так много комментариев.

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

  • Юридические уведомления, такие как авторские права
  • Если вы не можете использовать имя функции, чтобы что-то объяснить
  • Ваше намерение принять решение
  • Уточнение кода, который вы не можете изменить, например, результаты вызова библиотеки
  • Предупреждение о последствиях
  • TODO (в разумной степени)
  • Усилить важность чего-то, казалось бы, несущественного.
  • Javadocs в общедоступных API

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

ответил Karl Bielefeldt 15 thEurope/Moscowp30Europe/Moscow09bEurope/MoscowThu, 15 Sep 2011 01:27:34 +0400 2011, 01:27:34
8

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

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

Дядя Боб Мартин в своей книге «Чистый код» выступает за использование комментариев для следующих целей:

  1. Объяснение намерения
  2. Разъяснение
  3. Предупреждения
  4. Усиление
  5. Todos

Как минимум, комментарии должны описывать, что делает каждый публичный член, и как его использовать, а также объяснять все параметры и возвращать значения с приемлемыми диапазонами (например, между 1 и 1000) для каждого.

ответил Robert Harvey 15 thEurope/Moscowp30Europe/Moscow09bEurope/MoscowThu, 15 Sep 2011 01:34:16 +0400 2011, 01:34:16
5

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

Комментарии также могут сообщить вам , почему он делает это.

'мы сохраняли строки до 128 байт, потому что есть наследие компонент, который ломается, когда он превышает это значение

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

Вы бы предложили это?

'write_but_do_not_exceed_the_limits_that_the_legacy_component_can_handle ()'

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

ответил pbernatchez 14 WedEurope/Moscow2011-12-14T11:47:09+04:00Europe/Moscow12bEurope/MoscowWed, 14 Dec 2011 11:47:09 +0400 2011, 11:47:09
2

комментарии не о том, как работает приложение, они за то, почему эта функция достигает своих целей с использованием X. Если код плохо написан и не имеет имен функций, описывающих их действия, то добавление строки для каждой функции для этого было бы целесообразным использование комментариев в качестве полосовой помощи. Мне кажется, что вы не понимаете, как читать код, если вы не можете понять, как это работает. Если вы имели в виду то, что делает код, это должно быть объяснено во внешних документах, таких как примеры использования или потоки процессов и диаграммы проектирования. Также кажется, что вы приближаетесь к изучению кода с неправильного угла. Если ваш код не находится в одной функции длиной 50000 строк, длина не имеет значения, она просто зацикливается на том, насколько она велика. Вы изучаете сложную сложную систему по частям, выбираете слой /класс и узнаете, что он делает по отношению к проекту и как он работает, затем выберите другой и повторите. Его также полезно работать над пониманием потока высокого уровня вашего приложения, прежде чем пытаться изучить детали реализации на низком уровне.

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

ответил Ryathal 8 ThuEurope/Moscow2011-12-08T23:20:48+04:00Europe/Moscow12bEurope/MoscowThu, 08 Dec 2011 23:20:48 +0400 2011, 23:20:48
1

Полезные точки комментариев:

  • Определите, почему существует метод для выполнения X.
  • Определите, какие входы /выходы метода так, чтобы было ясно, следует ли изменять параметры, например. если при передаче в течение нескольких миллисекунд или секунд могут быть внесены изменения.
  • Определить побочные эффекты метода, например. есть ли другие вещи, которые он может знать, помимо своих первоначальных намерений? (Это должно быть редко, конечно)
  • Поместите примечание в код, что что-то имеет «запах кода» и стоит как-то подумать о рефакторинге.
  • Поместите примечание в код, чтобы объяснить, почему kludge был заперт в том месте, где он есть, что довольно похоже на предыдущую точку.
ответил JB King 15 thEurope/Moscowp30Europe/Moscow09bEurope/MoscowThu, 15 Sep 2011 01:29:10 +0400 2011, 01:29:10
1

Думали ли вы использовать Javadoc (или Doxygen или любой другой подобный инструмент)? Если это так, вы можете использовать (также) аргумент о том, что он может генерировать легко конкретизированную ссылку API-интерфейсов приложений (и даже диаграмм) в HTML, доступную для всех.

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

ответил dgimenes 15 thEurope/Moscowp30Europe/Moscow09bEurope/MoscowThu, 15 Sep 2011 01:59:17 +0400 2011, 01:59:17
1

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

ответил HLGEM 8 ThuEurope/Moscow2011-12-08T22:57:21+04:00Europe/Moscow12bEurope/MoscowThu, 08 Dec 2011 22:57:21 +0400 2011, 22:57:21
0

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

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

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

ответил NoChance 14 WedEurope/Moscow2011-12-14T12:36:52+04:00Europe/Moscow12bEurope/MoscowWed, 14 Dec 2011 12:36:52 +0400 2011, 12:36:52

Похожие вопросы

Популярные теги

security × 330linux × 316macos × 2827 × 268performance × 244command-line × 241sql-server × 235joomla-3.x × 222java × 189c++ × 186windows × 180cisco × 168bash × 158c# × 142gmail × 139arduino-uno × 139javascript × 134ssh × 133seo × 132mysql × 132