Стиль документации

Question

Из учебного плана для одного из моих классов программирования: «Вашей документации будет достаточно, если можно будет прочитать только комментарии, не глядя на код, и объяснить, что делает код».Кто-нибудь из вас слышал о таком стиле документации?Это хорошая практика?Мне кажется, это слишком усердно.

Answer 1

Код должен быть легко понятен. Это может быть достигнуто несколькими способами:

1. подходящее и значимое наименование
2. комментирование особо сложных алгоритмов или сложного кода
3. обширная документация по всему коду

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

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

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

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

Answer 2

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

Answer 3

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

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

Answer 4

Инструкция расплывчата. Вам следует обратиться за разъяснениями к своему инструктору.

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

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

Answer 5

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

Answer 6

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