Позвольте мне прояснить потенциальную путаницу в самом начале. Моя напыщенная речь не генерируется автоматически. Автогенерация комментариев является его объектом. То, что я должен сказать об этой мерзости, можно суммировать в шести словах: почему, почему, почему, почему и почему? Ох и седьмой
ЗАЧЕМ?
Я говорю о тех удобных маленьких комментариях JavaDoc, которые хорошо генерируются для вас хорошо известными IDE вместе с аксессорами свойств в стиле JavaBean, новыми классами и, действительно, в любое время, когда в руки попадает «волшебник» (моющий рот с мылом и водой) ваш проект. Вот особенно отвратительный пример, который я нашел на работе в последнее время. Псевдонимы были использованы.
пакет bet3.gov.it.abc;
// импорт заявлений
/ **
* <p>
* Coordonnée physique
* </ p>
* <p>
* <b> © Copyright 2010 B3IT - Betelgeuse 3 World Government. </ b>
* </ p>
* <p>
* <b> Société </ b>: B3IT - Мировое правительство Бетельгейзе 3 {@link <a href="http://it.gov.bet3"> B3IT - Мировое правительство Бетельгейзе 3 </a>}
* </ p >
* <p>
* <b> Projet </ b>: abc-service
* </ p>
* <p>
* <b> История изменений </ b>: <br>
* <br>
* 4 января. 2010 - Creation du Fichier. <br>
* <! - date - {@link <a href = ""> lien vers JIRA </a>} -> <br>
* </ p>
*
* @author bloggsj
* /
Открытый класс Coordonnee реализует Serializable {
/ ** La constante serialVersionUID. * /
private static final long serialVersionUID = -6370799192505622281L;
/ ** Ле / ля электронная почта. * /
частная строковая электронная почта;
/ ** Ле / ля факс. * /
личный струнный факс;
/ ** Le / La ID. * /
личный длинный идентификатор;
/ **
* Permet d'obtenir la valeur de "email".
*
* @return la valeur de "email"
* /
public String getEmail () {
return email;
}
/ **
* Permet d'obtenir la valeur de "fax".
*
* @return la valeur de "fax"
* /
public String getFax () {
возврат факса;
}
/ **
* Permet d'obtenir la valeur de "id".
*
* @return la valeur de "id"
* /
public long getId () {
return id;
}
/ **
* Affecte à l'objet la valeur "электронная почта".
*
* @param email la nouvelle valeur de "email"
* /
public void setEmail (String email) {
this.email = email;
}
/ **
* Affecte à l'objet la valeur "факс".
*
* @param fax la nouvelle valeur de "fax"
* /
public void setFax (String fax) {
this.fax = факс;
}
/ **
* Affecte à l'objet la valeur "id".
*
* @param id la nouvelle valeur de "id"
* /
public void setId (long id) {
this.id = id;
}
// множество кратких свойств для краткости остановлено - я думаю, что вы все равно получили картину
}
Цель комментария — помочь понять код. Это достигается путем предоставления информации, которая либо отсутствует, либо ее трудно вывести из кода.
Давайте не будем забывать, что комментарий имеет цену. Это добавляет объем к исходному коду, мешая читателю. Он добавляет дополнительный текст для изменения в случае обслуживания (хотя могут помочь инструменты рефакторинга). Это должно оправдать эту стоимость добавленной стоимостью.
Комментарий, который просто повторяет информацию в сигнатуре метода, не может иметь никакого дополнительного значения. Большинство IDE уже объявляют сигнатуру метода с помощью подсветки синтаксиса, автозаполнения и всплывающих подсказок, причем более заметно, чем сопровождающий комментарий.
Теперь я знаю, что вы можете отключить автоматическую генерацию комментариев и получить генерацию методов доступа без комментариев. Но автогенерация включена по умолчанию, и большинство разработчиков не выключают ее. Это подводит нас к моему первому вопросу: почему? Почему производители IDE думают, что вообще есть смысл автоматически генерировать комментарии? С какой стати они думают, что он должен быть включен по умолчанию? И почему, почему, почему большинство разработчиков не выключают его? Что у них может быть между ушами, чтобы увидеть какое-либо использование в исходном файле на три четверти полных абсолютно бесполезного шума? Ява уже достаточно многословна. Нет необходимости добавлять еще ненужную болтовню.
(О, кстати — приведенный выше код особенно отвратителен, потому что он не использует автоматическую генерацию комментариев в IDE. Кто-то фактически столкнулся с проблемой настройки собственного бессмысленного генератора комментариев.)