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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

print $foo; # this prints "bar"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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