Должен ли я писать JavaDoc для частных или защищенных методов? А как насчет частных переменных?
Я вижу примеры классов в моей книге Java, а частные переменные - JavaDoc'ed. Поэтому я не могу понять, является ли JavaDoc хорошей практикой для частных (или защищенных) методов.
Да, вы должны написать JavaDoc для частных методов, и даже если это только для вас. Через 3 года, когда вам нужно изменить код, вы будете счастливы, что задокументировали его.
Если вы покинете компанию или работаете над другим проектом, ваши сотрудники будут рады иметь документированный код. Недокументированный код имеет гораздо меньшее значение.
И посмотрите, как это делают настоящие профессионалы. Вот отрывок из исходного кода класса ArrayList Sun Microsystems:
/**
* The array buffer into which the elements of the ArrayList are stored.
* The capacity of the ArrayList is the length of this array buffer.
*/
private transient Object[] elementData;
Первый вопрос, который вам нужно задать себе, - "зачем вообще писать JavaDocs?" Для кого они полезны? Кто попросил вас написать их?
Скорее всего, кто-то (работодатель/профессор) попросил вас документировать некоторые из ваших методов. Это, как правило, хорошая вещь, но поставляется с затратами: дополнительное обслуживание.
Если у вас есть общедоступная версия ваших документов (например, если вы их создаете и публикуете в Интернете для конечных пользователей), имеет смысл документировать все, что вам нужно знать конечным пользователям. Сюда входят все общедоступные классы и методы.
Что вы для себя и других разработчиков?
Я считаю, что вы не должны использовать javadocs для внутренних и частных методов и классов. Основная причина в том, что javadocs в первую очередь приносит пользу тем, кто потребляет, а не поддерживает ваш код.
С другой стороны, вам нужно хранить заметки и комментарии по своему собственному коду, который часто является внутренним. В этом случае я бы предложил обычные комментарии (например, //); это меньше обслуживания, и часто, одинаково ясно, с гораздо меньшим набором текста.
С другой стороны, если метод становится общедоступным, может быть полезно преобразовать эти комментарии в настоящие javadocs. Javadocs имеет преимущество заставлять вас думать (и документировать) каждый параметр, исключение и возвращаемое значение.
Компромисс за вами.
Нет, вы не должны писать javadoc для частных методов. Конечные пользователи не имеют доступа к частным полям или методам, поэтому на самом деле нет смысла предоставлять javadoc для них. Частные поля и методы предназначены только для разработчика. Если вам действительно нужно, не стесняйтесь писать комментарии для неочевидной логики. Вероятно, вы должны написать javadoc для методов protected, потому что эти методы иногда переопределяются, и полезно предоставить пользователю некоторую информацию о том, что делает этот метод или должен делать.
Вы часто слышите общую рекомендацию, что в лучшем случае комментарии просто не нужны вообще. Но в отношении JavaDoc они играют важную роль не только для разработчика, но и для пользователя библиотеки.
Кроме того, запись комментариев JavaDoc может быть более полезной для вас (особенно для новичков), чем для кого-либо еще: когда вам трудно описать, что такое переменная или что метод делает с одним /** One-line-JavaDoc comment */, тогда вы "Я буду автоматически переосмысливать то, что вы там сделали.
При создании JavaDocs вы можете выбрать, хотите ли вы генерировать их только для частей public и protected API, а также для элементов по умолчанию или private.
Однако вы должны в любом случае использовать методы документа protected. Может ли кто-то, кто расширяет класс, вызвать этот метод только, или ему также разрешено переопределить этот метод? Если да, есть ли какие-либо предварительные и постконфиденциальные условия, о которых он должен знать? Должен ли он вызвать super.theMethod() в переопределенной версии? (BTW: Если ему не разрешено переопределять метод, тогда он должен быть final, но документирован так или иначе)
Кстати: я лично прокомментирую все, но знаю, что большинство людей считают, что это не нужно или даже плохой стиль, особенно для "тривиальных" вещей
/**
* The number of elements in this set
*/
private final int numberOfElements;
Я думаю, что это не наносит вреда, но помогает во многих случаях. Возможно, что касается частей private, это просто вопрос вкуса.
Вам не нужно javadoc ничего, но это очень полезно. Больше javadocs никогда не бывает плохо.
По вашему вопросу, если вы используете компилятор документации javadoc, javadocs будет скомпилирован для защищенных методов, но не частных методов. Однако нет причин, по которым они еще не могут использоваться в качестве кодовых комментариев.