Считаются ли комментарии формой документации?

11

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

Не будет ли это:

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

считать документацией, особенно если разработчик использует мой код? Или документация считается за пределами самого кода?

динамический
источник
11
Если вы используете систему генерации документов, такую ​​как JavaDocs или Doxygen, комментарии - это буквально документация.
Gort the Robot
5
ЯНГНИ ( xprogramming.com/Practices/PracNotNeed.html ). Документируйте свой код в соответствии с вашими требованиями. Позвольте клиенту (если он вообще есть) заплатить вам, чтобы написать документацию для своего удовлетворения. Не беспокойтесь о том, что многие люди говорят с вами (если они вам не платят).
Эмори
1
Из ваших двух комментариев второй бесполезен, почему бы не заменить $ foo на bar. Если это не так, то комментарий неправильный. Первый комментарий неверен. Это задание.
Ctrl-Alt-Delor
2
Когда вы захотите добавить комментарий, измените свой код так, чтобы он не нуждался в комментариях. Все - документация, код - документация. Комментарии обычно не содержат [дополнительной] информации или являются ошибочными. Задокументируйте намерение что (кодовые контракты могут помочь с этим) и почему. Держите документацию близко к коду, используйте комментарии. Документация поверх документов: комментарии над документами, четкий код над комментариями.
Ctrl-Alt-Delor
2
Является ли YANGNI "вам это не понадобится"
Chris S

Ответы:

27

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

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

Oleksi
источник
3
«Для большинства проектов комментарии являются основной (если не единственной) формой проектной документации». - заманчиво понизить это, но, к сожалению, это должно быть признано истинным утверждением. Однако я надеюсь, что вы не собираетесь утверждать, что так и должно быть.
Эдвард Стрендж
2
Я действительно не согласен с этим, поскольку единственная надежная документация, которую вы имеете, это сам исходный код. Оба комментария и «документация» должны сопровождаться кодом, что случается редко. Таким образом, единственным надежным источником документации является ваш код!
Мартиерт
3
@martiert Раньше я чувствовал то же самое, но я обнаружил, что на практике это не очень хорошо работает. Все эти комментарии «почему» гораздо понятнее комментариев, чем попытки извлечь знания «почему» из кода. Конечно, код самодокументирования можно (и нужно) использовать для удаления большинства комментариев, но иногда комментарий - это самый простой, понятный и наиболее эффективный по времени способ документирования чего-либо.
Олекси
3
@martiert Проблема с самодокументируемым кодом заключается в том, что он не разрешает ссылки на документацию в других местах. Одними из лучших комментариев в коде, которые я когда-либо видел, были ссылки на научные статьи, в которых объяснялись детали используемого алгоритма или выбор магических констант. Никакое количество самодокументирования не поможет избежать того факта, что некоторая критическая документация просто неочевидна. «Почему» часто попадает в эту категорию, а иногда и «как» тоже.
Donal Fellows
3
Также обратите внимание, что комментарии на многих языках используются для создания фактической документации ... так что они часто являются одними и теми же. Смотрите MSDN в качестве примера.
Стивен Эверс
12

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

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

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

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

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

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

MathAttack
источник
17
Самодокументированный код - ложь.
Яннис
1
@YannisRizos Больше похоже на недостижимую цель, чем на откровенную ложь.
Пламя Птариена
2
@YannisRizos: вы можете быть правы, но код, который требует много комментариев, почти всегда является очень плохим кодом и может быть почти всегда написан так, что требует меньше комментариев.
Док Браун
9
@DocBrown Зависит. Я видел людей, документирующих циклы, и я видел людей, утверждающих, что 100 лок бизнес-логики были самодокументированы. Факт заключается в том, что чрезмерные комментарии не могут повредить (кроме случаев, когда они устарели / неверны), и если мне придется выбирать между чрезмерным комментированием и самодокументированным кодом, я всегда буду выбирать первый. Конечно, я бы предпочел сбалансированные и точечные комментарии, как описывает Олекси .
Яннис
1
@MathAttack Большинство достойных IDE могут скрывать / складывать комментарии. Но да, иногда они просто мешают.
Яннис
3

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

Я знаю, что вы имели в виду это в качестве примера, но такие вещи, как

print $foo; # this prints "bar"

не полезно; это просто добавляет визуальный беспорядок. Не документируйте очевидное.

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

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

Джон Боде
источник
3

Я считаю, что придерживаться подхода Боба Мартина к этому из Чистого кода, как правило, решает проблему того, считаете ли вы, что вы слишком комментируете или комментируете и оставляете документацию:

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

... соотношение времени, потраченного на чтение и письмо, превышает 10: 1. Мы постоянно читаем старый код как часть усилий по написанию нового кода.

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

Крис С
источник
2

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

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


источник
1
Действительно сложный материал должен быть в академической статье (или, иногда, в патенте).
Donal Fellows
2

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

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

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

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

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

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

Майк Хоган
источник