Почему конструкторы javadoc без параметров?

В статье 56 «Эффективной Java» (третье издание) Джошуа Блох утверждает: «Общие классы не должны использовать конструкторы по умолчанию, потому что нет возможности предоставить для них комментарии к документам».

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

Я могу понять это, если класс имеет интересное поведение в блоках инициализатора (поскольку в противном случае их негде комментировать) или даже нестандартные назначения значений для полей (возможно, вызов методов для получения начальных значений). Но похоже, что для большинства классов это мало что добавляет. Есть что-то, что мне не хватает?


person Tom Tresansky    schedule 19.03.2018    source источник
comment
пункт 56 в EJ-3rd edition - это другая тема: i.imgur.com/OjKxK4s.png   -  person ΦXocę 웃 Пepeúpa ツ    schedule 19.03.2018
comment
Чтобы уточнить, связан ли вопрос с javadocs для конструкторов по умолчанию или речь идет о комментариях javadoc для конструкторов не по умолчанию, но без параметров?   -  person Tin Wizard    schedule 20.03.2018
comment
Эта строка находится в пункте 56 в 3-м издании. Та тема самая правильная.   -  person Tom Tresansky    schedule 20.03.2018
comment
Вопрос в необходимости добавления явных конструкторов без аргументов только для их документирования.   -  person Tom Tresansky    schedule 20.03.2018


Ответы (1)


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

Теперь в некоторых других случаях полезно задокументировать, что делает метод, и, в частности, его состояние по умолчанию.

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

Вот два примера классов JDK, где javadoc может принести полезную информацию для конструкторов с пустым телом.

Стек

/**
 * Creates an empty Stack.
 */
public Stack() {
}

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

Атомное целое

Возьмем пустой конструктор AtomicInteger:

/**
 * Creates a new AtomicInteger with initial value {@code 0}.
 */
public AtomicInteger() {
}

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

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

person davidxxx    schedule 19.03.2018
comment
В этом вы правы, за исключением того, что это просто конструктор без параметров, а не конструктор по умолчанию. В случае конструктора по умолчанию у вас не может быть никакого другого конструктора, поэтому все, что вам нужно документировать, может быть частью документации класса. - person v6ak; 19.03.2018
comment
@ v6ak Действительно. Это первый найденный в голове пример из JDK. Я постараюсь найти настоящий по умолчанию :) - person davidxxx; 19.03.2018
comment
Stack имеет явный единственный конструктор, который действует как конструктор по умолчанию с Javadoc Creates an empty Stack. - person d.j.brown; 20.03.2018
comment
@d.j.brown Ты лучше, чем Google :) - person davidxxx; 20.03.2018
comment
@ d.j.brown Я вижу, что такие случаи есть, но я считаю, что причины для помещения информации в такие конструкторы без параметров без альтернатив довольно академичны. В этом нет ничего плохого, но мы могли бы жить и без этого. - person v6ak; 20.03.2018
comment
Я согласен, и в большинстве случаев это кажется излишним. Я предполагаю, что смысл, который пытается донести Блох, заключается в том, что все аспекты открытого API должны быть задокументированы, а конструкторы по умолчанию предотвращают это. - person d.j.brown; 20.03.2018