Как установить setuptools?

@Claudiu

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

@Daniel Spiewak

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

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

@Paul de Vrieze

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

/** 
 * 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-редактора - функция. Например, постоянный - который является частной статической последней переменной - должен иметь javadoc, особенно когда его значение не тривиально. Рассматриваемый вопрос: regexp (его javadoc должен, включает regexp в свою незавершенную форму, что является целью, и литеральный пример, подобранный regexp)
• , Это может быть проанализировано внешними инструментами (как xdoclet)

@Domci

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

@Miguel Ping

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