Вы используете Javadoc для каждого метода, который Вы пишете? [закрытый]

Необходимо, вероятно, документировать все методы действительно. Самый важный общедоступные методы API (особенно опубликовал методы API). Закрытые методы иногда не документируются, хотя я думаю, что они должны быть, только для ясности - то же идет с защищенными методами. Ваши комментарии должны быть информативными, и не только повторить то, что делает код.

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

Можно автоматизировать поколение комментариев Javadoc для методов считывания/методов set от Eclipse через шаблоны кода, чтобы экономить на сумме документации, которую необходимо записать. другая подсказка должна использовать {$inheritDoc} для предотвращения дублирования комментариев к коду между интерфейсами и классами реализации.

в предыдущей компании мы раньше использовали средство форматирования кода драндулета с затмением. Это добавило бы javadoc ко всем методам включая частный.

Это сделало жизнь трудной зарегистрировать методы set и методов get. Но какого черта. Необходимо сделать это - Вы делаете это. Это заставило меня изучить некоторую макро-функциональность с XEmacs:-), можно автоматизировать его еще больше путем записи синтаксического анализатора Java, и комментатор как создатель ANTLR сделал несколько лет назад:-)

в настоящее время, я документирую все открытые методы и что-либо больше чем 10 строк.

Я пытаюсь, по крайней мере документируют каждое общедоступное и интерфейсное свойство и метод, так, чтобы люди, звонящие в мой код, знали, каковы вещи. Я также пытаюсь прокомментировать как можно больше в строке также для пользы обслуживания. Даже 'персональные' проекты, которые я делаю в свободное время только для меня, я пробую к javadoc просто, потому что я мог бы полка он в течение года и возвратиться к нему позже.

Я делаю его точкой для записи комментариев Javadoc каждый раз, когда это нетривиально, Пишущий комментарии Javadoc при использовании IDE как затмение, или netbeans не настолько неприятен. Кроме того, когда Вы пишете комментарий Javadoc, Вы вынуждаетесь думать о не, что метод делает, но и что метод делает точно , и предположения, которые Вы сделали.

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

Можно выполнить javadoc против кода, который не имеет комментариев Javadoc, и это произведет довольно применимый javadocs, если Вы дадите вдумчивые имена своим методам и параметрам.

Я чувствую, что должны, по крайней мере, быть комментарии относительно принятых параметров и типы возврата с точки зрения того, каковы они.
можно пропустить детали реализации в случае, если имена функций описывают его полностью, для, например, sendEmail (..) ;

Существует другая причина, необходимо использовать javadocs. Для комментария чего-то необходимо понять его сначала. Когда Вы пытающийся прокомментировать функцию, Вы на самом деле взгляды из того, что делает метод/функция/класс, и это заставляет Вас быть более конкретными и ясными в Вашем javadoc, который в свою очередь заставляет Вас записать более ясный и краткий код, который хорош.

Когда я пишу код для меня - НИКАКОЙ . В этом случае Java doccing является пустой тратой моего времени.

, Когда я запишу код, который другие будут использовать - Да . Каждый метод, который кто-то еще может использовать (любой открытый метод) должен иметь документ Java, по крайней мере, формулирующий его очевидную цель. Для хорошего теста - выполняет javadoc утилиту создания на Вашем коде (я забываю точную командную строку теперь). Просмотрите веб-страницу, которую это генерирует. Если Вы были бы удовлетворены, пользуясь библиотекой с тем уровнем документации, Вы являетесь золотыми. В противном случае Запись больше javadocs в Вашем коде .

Все основания, перепетые другими уже; одно дополнительное примечание:

, Если Вы делаете это:

/**
 * This method currently launches the blaardh into the bleeyrg.
 */
void execute() { ... }

Рассматривают изменение его в это:

void launchBlaardhIntoBleeyrg() { ... }

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

Наконец имеют в виду, что изменение не всегда требуется; например, поведение метода, как могут ожидать, будет развиваться со временем (отмечайте слово "в настоящее время" в JavaDoc).

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

1. API, классы платформы и внутренние допускающие повторное использование статические методы должны быть прокомментированы полностью.

2. Логика в каждой сложной части кода должна быть объяснена на двух местах - общая логика в javadoc и логика для каждой значимой части кода в своем собственном комментарии.

3. свойства Model должны быть прокомментированы, если они не очевидны. Например, никакой смысл в комментарии имени пользователя и пароля, но типа не должен, по крайней мере, иметь комментарий, в котором говорится, что является возможными значениями для типа.

4. я не документирую методов get, методы set или что-либо сделанное "книгой". Если у команды есть стандартный способ создать формы, адаптеры, контроллеры, фасады... Я не документирую их, так как нет никакого смысла, если все адаптеры являются тем же и имеют ряд стандартных методов. Любой знакомый с платформой будет знать то, что они для - предполагающий, что философия платформы и способ работать с нею документируются где-нибудь. В этом случается, комментарии означают дополнительную помеху и не имеют никакой цели. Существуют исключения к этому, когда класс делает что-то нестандартное - тогда, короткий комментарий полезен. Кроме того, даже если я создаю форму стандартным способом, мне нравится делить части формы с короткими комментариями, которые делят код на несколько частей, например, "адрес выставления счета запускается здесь".

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

Для вещей, как тривиальные методы get и методы set, совместно используют комментарий между тогда и описывают цель свойства, не метода get/метода set.

/** 
 * 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;
}

И да, это - больше работы.

Если метод, очевидно самоочевиден, я мог бы пропустить комментарий Javadoc.

Комментарии как

/** Does Foo */
 void doFoo();

Действительно не настолько полезны. (Чрезмерно упрощенный пример, но Вы получаете идею)

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

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

просто помещенный: ДА

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

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