codestyle; поставить Javadoc до или после аннотации?

184

Я знаю, что это не самая насущная проблема, но я только что понял, что могу поставить блок комментариев Javadoc до или после аннотации. Что бы мы хотели принять в качестве стандарта кодирования?

/**
 * This is a javadoc comment before the annotation 
 */
@Component
public class MyClass {

    @Autowired
    /**
     * This is a javadoc comment after the annotation
     */
    private MyOtherClass other;
}
java coding-style annotations javadoc code-documentation Пол Маккензи
источник

Ответы:

191

До аннотации, поскольку аннотация - это код, который «принадлежит» классу. Смотрите примеры с javadoc в официальной документации.

Вот случайный пример, который я нашел на другой официальной странице Java :

/**
 * Delete multiple items from the list.
 *
 * @deprecated  Not for public use.
 *    This method is expected to be retained only as a package
 *    private method.  Replaced by
 *    {@link #remove(int)} and {@link #removeAll()}
 */
@Deprecated public synchronized void delItems(int start, int end) {
    ...
}
Питер Ярич
источник
8
Также здесь интерес - аннотация находится в той же строке, что и другие квалификаторы метода. Я никогда не видел, чтобы это было сделано раньше, но кажется, что к аннотациям следует относиться так же, как и к другим определителям метода, и поэтому Javadoc определенно должен идти перед ним.
ArtOfWarfare
8
Размещение одних и тех же аннотаций в одной строке может быстро выйти из-под контроля, если вы используете что-то тяжелое, как Джексон. Я помещаю каждую аннотацию в отдельную строку.
WW.
17

Я согласен с уже даными ответами.

Аннотации являются частью кода, а Javadoc - частью документации (отсюда и название).

Поэтому для меня разумно хранить части кода вместе.

perdian
источник
11

Все сводится к читабельности. На мой взгляд, код более читабелен с аннотациями непосредственно над методом / полем.

Робби Понд
источник
11

Помимо стандарта кодирования, кажется, что инструмент javadoc не обрабатывает комментарии javadoc, если они размещены после аннотаций. Работает нормально в противном случае.

shadrik
источник
0

Я согласен со всем вышеперечисленным. Другим может быть полезно, чтобы шаблоны стилей кода IntelliJ (Idea) не давали ложно положительный результат (если @throws указан правильно, он предупреждает) и ложно отрицательный (когда @throws не указан, но должен быть) при использовании стиля RestEasy аннотаций. Я ставлю свои javadocs выше всего остального, затем аннотации, затем код.

Смотрите отчет об ошибке здесь: https://youtrack.jetbrains.com/issue/IDEA-220520

Макс П Маги
источник