Блог

При создании частной или защищенной переменной, метода, класса и т.д. Следует ли комментировать ее комментарием к документации?

Да! Комментарии предназначены для того, чтобы помочь любому разработчику, включая вас, при проверке, поддержании или расширении кода в будущем. То, является ли это общедоступным / частным, не должно влиять на фактор, проще говоря, если вы считаете, что что-то недостаточно ясно без комментария, добавьте его.

(Конечно, лучшая документация — это, в первую очередь, понятный самодокументируемый код)

Некоторые люди, без сомнения, скажут вам, что ничего не нужно комментировать (и технически они правы в том, что комментарии не влияют на результат). Однако это зависит от «стиля кодирования», как вы его пометили. Я лично всегда комментирую все переменные в дополнение к присвоению им описательного имени. Помните, что другие люди могут захотеть работать с вашим исходным кодом, или вы можете захотеть сделать это через годы, и в этом случае стоит потратить несколько секунд на документирование этого, пока вы все еще знаете, что это делает.

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

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

Например, если EditablePolygon класс в Java может содержать четыре основных поля:

 int[] xCoords;
int[] yCoords;
int numCoords;
int sharedPortion;
  

и ожидайте соблюдения инвариантов, согласно которым оба массива всегда будут иметь одинаковую длину, и эта длина будет равна >= numCoords, а все интересующие координаты будут находиться в слотах массива ниже numCoords . Далее может быть указано, что может существовать несколько EditablePolygon объектов, совместно использующих одни и те же массивы, при условии, что все такие объекты, кроме одного, имеют длину, sharedPortion большую numCoords или равную длине массива, и что значение одного объекта sharePortion не меньше numCoords значения любого из других [для создания клона формы требуется защитная копия, если не запрашивается изменение части оригинала, которая была совместно использована с клоном, или любой части клона [которая полностью совместно используется с оригиналом].

Обратите внимание, что наиболее важными моментами для комментариев к документу являются (1) длина массива может превышать количество точек, и (2) определенные части массива могут быть общими. Первое может быть несколько очевидным из кода, но второе, скорее всего, будет гораздо менее очевидным. Поле sharedPortion действительно имеет некоторое значение само по себе, но его значение и назначение действительно можно понять только в связи с другими переменными.

Хорошей практикой является документирование методов и классов. Более того, следует уделять больше внимания javadocs для общедоступных методов, поскольку они действуют как справочное руководство для внешних объектов. Аналогичным образом Javadoc может быть полезен для общедоступных переменных, хотя лично я не сторонник наличия комментариев для переменных.