Следует ли комментировать закрытые и защищенные переменные, методы и классы?

Question

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

Answer 1

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

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

Answer 2

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

Answer 3

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

Answer 4

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

Answer 5

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

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

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

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

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