Должен ли я писать Doc-комментарии для всех моих java-методов?
Используете ли вы Javadoc для каждого метода, который вы пишете?
Ответ 1
@Claudiu
Когда я пишу код, который другие будут использовать - Да. Каждый метод, который может использовать кто-то другой (любой общедоступный метод), должен иметь javadoc, по крайней мере, указывая на его очевидную цель.
@Даниэль Спивак
Я тщательно документирую каждый публичный метод в каждом классе API. Классы, которые имеют публичные элементы, но не предназначенные для внешнего потребления, заметно выделяются в классе javadoc. Я также документирую каждый защищенный метод в каждом классе API, хотя и в меньшей степени. Это говорит о том, что любой разработчик, который расширяет класс API, уже будет иметь справедливое представление о том, что происходит.
Наконец, я буду иногда документировать частные и пакетные частные методы для моей собственной выгоды. Любой метод или область, которые, как мне кажется, нуждаются в некотором объяснении в ее использовании, получат документацию, независимо от ее видимости.
@Paul de Vrieze
Для вещей, таких как тривиальные геттеры и сеттеры, поделитесь комментарием между ними и опишите цель свойства, а не геттера/сеттера
/**
* Get the current value of the foo property.
* The foo property controls the initial guess used by the bla algorithm in
* {@link #bla}
* @return The initial guess used by {@link #bla}
*/
int getFoo() {
return foo;
}
И да, это больше работы.
@VonC
Когда вы нарушаете огромный комплексный метод (из-за причины высокой цикломатической сложности):
- один публичный метод, вызывающий
- несколько частных методов, которые представляют собой внутренние шаги публичного
очень полезно также javadoc для частных методов, хотя эта документация не будет видна в файлах javadoc API.
Тем не менее, это позволяет вам легче запомнить точный характер различных шагов вашего сложного алгоритма.
И помните: предельные значения или граничные условия должны быть частью вашего javadoc.
Плюс, javadoc лучше, чем просто "//комментарий" :
- Он распознается IDE и используется для отображения всплывающего окна при перемещении курсора поверх одной из ваших javadoc-ed-функций. Например, константа - частная статическая конечная переменная - должна иметь javadoc, особенно когда ее значение не является тривиальным. Пример: regexp (его javadoc должен содержать регулярное выражение в своей неэкранированной форме, то, что является целью, и литерал, сопоставляемый регулярным выражением)
- Его можно проанализировать с помощью внешних инструментов (например, xdoclet)
@Domci
Для меня, если кто-то увидит это или нет, это не имеет значения - вряд ли я буду знать, что некоторые неясные фрагменты кода, которые я написал, делают через пару месяцев. [...]
Короче говоря, логика комментариев, а не синтаксис, и делайте это только один раз, в нужном месте.
@Мигель Пинг
Чтобы что-то прокомментировать, вы должны понять это в первую очередь. Когда вы пытаетесь прокомментировать функцию, вы на самом деле думаете о том, что делает метод/функция/класс, и это делает вас более конкретным и ясным в вашем javadoc, что, в свою очередь, заставляет вас писать более четкий и сжатый код, что хорошо.
Ответ 2
Если этот метод, очевидно, явный, я могу пропустить комментарий javadoc.
Комментарии, похожие на
/** Does Foo */ void doFoo();
Действительно, это не так полезно. (Слишком упрощенный пример, но вы понимаете)
Ответ 3
Я тщательно документирую каждый публичный метод в каждом классе API. Классы, которые имеют публичные элементы, но не предназначенные для внешнего потребления, заметно выделяются в классе javadoc. Я также документирую каждый защищенный метод в каждом классе API, хотя и в меньшей степени. Это говорит о том, что любой разработчик, который расширяет класс API, уже будет иметь справедливое представление о том, что происходит.
Наконец, я буду иногда документировать частные и пакетные частные методы для моей собственной выгоды. Любой метод или область, которые, как мне кажется, нуждаются в некотором объяснении в ее использовании, получат документацию, независимо от ее видимости.
Ответ 4
Для вещей, таких как тривиальные геттеры и сеттеры, делиться комментарием между ними и описывать назначение свойства, а не геттера/сеттера.
/**
* Get foo
* @return The value of the foo property
*/
int getFoo() {
return foo;
}
Является не полезным. Лучше сделайте что-нибудь вроде:
/**
* Get the current value of the foo property.
* The foo property controls the initial guess used by the bla algorithm in
* {@link #bla}
* @return The initial guess used by {@link #bla}
*/
int getFoo() {
return foo;
}
И да, это больше работы.
Ответ 5
Все базы, на которые ссылаются другие; еще одно примечание:
Если вы это сделаете:
/**
* This method currently launches the blaardh into the bleeyrg.
*/
void execute() { ... }
Подумайте об этом:
void launchBlaardhIntoBleeyrg() { ... }
Это может показаться немного очевидным, но во многих случаях возможность легко пропустить в вашем собственном коде.
Наконец, имейте в виду, что изменение не всегда требуется; например, поведение метода можно ожидать с течением времени (обратите внимание на слово "в настоящее время" в JavaDoc).
Ответ 6
Когда я пишу код для себя - NO. В этом случае joc doccing является пустой тратой моего времени.
Когда я пишу код, который другие будут использовать - Да. Каждый метод, который может использовать кто-то другой (любой публичный метод), должен иметь документ java, по крайней мере, указывая на его очевидную цель. Для хорошего теста - запустите утилиту создания javadoc для вашего кода (я забыл точную командную строку сейчас). Просмотрите веб-страницу, которую он создает. Если вы будете удовлетворены использованием библиотеки с этим уровнем документации, вы будете золотыми. Если нет, Напишите больше javadocs в свой код.
Ответ 7
Есть еще одна причина, по которой вы должны использовать javadocs. Чтобы что-то прокомментировать, вы должны понять это в первую очередь. Когда вы пытаетесь прокомментировать функцию, вы на самом деле думаете о том, что делает метод/функция/класс, и это делает вас более конкретным и ясным в вашем javadoc, что, в свою очередь, заставляет вас писать более четкий и сжатый код, что хорошо.
Ответ 8
Нет, не комментируйте каждый метод, переменную, класс и т.д.
Вот цитата из "Чистого кода: руководство по гибкому программному мастерству":
Просто глупо иметь правило, в котором говорится, что каждая функция должна иметь javadoc, или каждая переменная должна иметь комментарий. Комментарии вроде этого просто беспорядок вверх по коду, popagate ложь и придает общую путаницу и дезорганизацию.
Комментарий должен существовать, если и только если он добавляет важную информацию для предполагаемого пользователя метода, переменной, класса и т.д. То, что составляет "важное", заслуживает рассмотрения и может быть напоминанием для меня, когда/если Я возвращаюсь к этому методу/классу/и т.д., Следствию/побочному эффекту метода, мотивации к тому, почему вещь вообще существует (в случае, когда какой-то код преодолевает недостаток/ошибку некоторой библиотеки или системы), важная информация о производительности или когда это целесообразно позвонить и т.д.
Что не является хорошим комментарием, но указывает, что сам код должен быть переписан/изменен, это комментарий, объясняющий детали сложного и неясного метода или функции. Вместо этого предпочитайте более короткий более четкий код.
Ответ 9
Для меня, если кто-то увидит это или нет, это не имеет значения - вряд ли я буду знать, что некоторые неясные фрагменты кода, которые я написал, делают через пару месяцев. Существует несколько рекомендаций:
-
API, рамочные классы и внутренние многоразовые статические методы должны быть тщательно прокомментированы.
-
Логика в каждом сложном фрагменте кода должна быть объяснена в двух местах - общая логика в javadoc и логика для каждой значимой части кода в ее собственном комментарии.
-
Свойства модели следует прокомментировать, если они не очевидны. Например, нет смысла комментировать имя пользователя и пароль, но тип должен по крайней мере иметь комментарий, который говорит, какие возможные значения для типа.
-
Я не документирую геттеры, сеттеры или что-либо, что сделано "по книге". Если у команды есть стандартный способ создания форм, адаптеров, контроллеров, фасадов... Я их не документирую, поскольку нет смысла, если все адаптеры одинаковы и имеют набор стандартных методов. Любой, кто знаком с фреймворком, будет знать, для чего они предназначены - предполагая, что философия рамки и способ работы с ней где-то документированы. В этом случае комментарии означают дополнительный беспорядок и не имеют никакой цели. Есть исключения из этого, когда класс делает что-то нестандартное - тогда короткий комментарий полезен. Кроме того, даже если я создаю форму стандартным образом, я хотел бы разделить части формы с короткими комментариями, которые делят код на несколько частей, например, "платежный адрес начинается здесь".
Короче говоря, логика комментариев, а не синтаксис, и делайте это только один раз, в нужном месте.
Ответ 10
На Java-документ не следует полагаться, поскольку он накладывает нагрузку на разработчиков, вносящих изменения в поддержку Java-документа, а также кода.
Имена классов и имена функций должны быть достаточно ясными, чтобы объяснять, что происходит.
Если объяснить, что класс или метод делает его имя слишком длинным для решения, класс или метод недостаточно сфокусированы и должны быть реорганизованы в более мелкие единицы.
Ответ 11
просто поставьте: ДА
Время, когда вам нужно подумать о том, следует ли писать документ, лучше вложить в документ документ.
Написание однострочного изображения лучше, чем тратить время на то, чтобы вообще не документировать метод в конце.
Ответ 12
Я считаю, что по крайней мере должны быть комментарии относительно принятых и возвращаемых параметров в терминах того, что они есть.
Можно пропустить детали реализации, если имена функций описывают его полностью, например, sendEmail (..);
Ответ 13
Вероятно, вам следует документировать все ваши методы. Наиболее важными являются общедоступные API-методы (особенно опубликованные методы API). Частные методы иногда не документируются, хотя я думаю, что они должны быть просто для ясности - то же самое касается защищенных методов. Ваши комментарии должны быть информативными, а не просто повторять, что делает код.
Если метод особенно сложный, рекомендуется документировать его. Некоторые люди считают, что код должен быть написан четко, чтобы он не требовал комментариев. Однако это не всегда возможно, поэтому в этих случаях следует использовать комментарии.
Вы можете автоматизировать создание комментариев Javadoc для getters/seters из Eclipse с помощью шаблонов кода, чтобы сэкономить объем документации, которую вы должны написать. другим советом является использование @{$ inheritDoc} для предотвращения дублирования комментариев кода между интерфейсами и классами реализации.
Ответ 14
в предыдущей компании мы использовали форматор jalopy code с eclipse. Это добавит javadoc ко всем методам, включая private.
Это затруднило жизнь документальным сеттерам и геттерам. Но что, черт возьми. Вы должны это сделать - вы это делаете. Это заставило меня изучить некоторые макрофункции с помощью XEmacs:-) Вы можете автоматизировать его еще дальше, написав Java-парсер и комментатор, как создатель ANTLR, сделал несколько лет назад: -)
В настоящее время я документирую все общедоступные методы и всего более 10 строк.
Ответ 15
Я стараюсь, по крайней мере, документировать все общедоступные свойства и метод интерфейса, чтобы люди, звонящие в мой код, знали, что это такое. Я также стараюсь комментировать как можно больше в строке, а также ради обслуживания. Даже "личные" проекты, которые я делаю в свое время только для себя, я пытаюсь выполнить javadoc только потому, что я могу поместить его на год и вернуться к нему позже.
Ответ 16
Я делаю все возможное, чтобы писать комментарии javadoc всякий раз, когда это нетривиально. Написание комментариев javadoc при использовании IDE, например eclipse или netbeans, не является чем-то неприятным. Кроме того, когда вы пишете комментарий javadoc, вам приходится думать не только о том, что делает этот метод, но и о том, что метод точно, и о сделанных вами предположениях.
Другая причина заключается в том, что, когда вы поняли свой код и реорганизовали его, javadoc позволяет забыть о том, что он делает, поскольку вы всегда можете ссылаться на него. Я не выступаю за то, чтобы забыть о том, что делают ваши методы, но только потому, что я предпочитаю запоминать другие вещи, которые важнее.
Ответ 17
Вы можете запустить javadoc против кода, который не имеет javadoc-комментариев, и он будет генерировать довольно полезные javadocs, если вы дадите продуманные имена вашим методам и параметрам.
Ответ 18
Предполагается, что во всех ответах пока что комментарии будут хорошими. Как мы все знаем, это не всегда так, иногда они даже неправильны. Если вам нужно прочитать код, чтобы определить его намерение, границы и ожидаемое поведение ошибки, комментарий отсутствует. Например, это метод потокобезопасный, может ли любой arg быть null, он может возвращать null и т.д. Комментарии должны быть частью любых обзоров кода.
Это может быть еще более важным для частных методов, поскольку разработчику базы кода придется бороться с проблемами, которые пользователь API не будет использовать.
Возможно, у IDE должна быть функция, которая позволяет использовать форма документирования, чтобы разработчик мог проверить различные свойства, которые важны и применимы для текущего метода.
Ответ 19
Javadoc может быть действительно полезен для библиотек и компонентов многократного использования. Но пусть будет более практичным. Более важно, чтобы я сам объяснял код, чем javadoc. Если вы представляете себе огромный проект с Javadocs, - вы бы на это положились? Я так не думаю... Кто-то добавил Javadoc, затем реализация изменилась, добавлена новая функция (удалена), поэтому Javadoc устарел. Как я уже говорил, мне нравится иметь javadocs для библиотек, но для активных проектов я бы предпочел
- малые функции/классы с именами, которые описывают, что они делают
- clear unit test случаи, которые дают объяснение, что function/classes do