Javadoc @author tag good practices

Question

Мне интересно узнать о лучших практиках при создании Javadocs. У меня есть проект со многими файлами. Код был создан многими разработчиками. Каждый файл имеет аннотацию @author, поэтому очевидно, кто создал определенный класс.

Но когда какой-либо другой разработчик добавляет новый код в файл, его изменяет и т. Д., Как он должен сообщить остальной команде, что он создал какую-то новую функцию или изменил существующий код? Другими словами, как мы должны «поддерживать совместимость Javadocs с реальностью»? ;)

• Добавить свое имя в существующую бирку @author? Тогда легче определить, кого спросить в случае каких-либо сомнений.
• Добавить тег @author в каждый новый метод, внутренний класс и т. Д.?

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

Каков наилучший способ использования этих @author тегов?

Answer 1

Я бы сказал, что для большинства целей @author - это нежелательный шум. Пользователь вашего API не должен - и, вероятно, не заботится или не хочет знать, кто написал какие части.

И, как вы уже сказали, SVN уже содержит эту информацию гораздо более авторитетным способом, чем код. Поэтому, если бы я был одной из команд, я всегда предпочел бы журнал SVN и проигнорировал бы @author. Готов поспорить, что код будет несовместим с реальностью, независимо от принятой вами политики. Следуя принципу «Не повторяй себя», зачем хранить эту информацию в двух местах?

Если, однако, существует какая-то бюрократическая или политическая причина, согласно которой эта информация ДОЛЖНА быть включена в код, рассмотрели ли вы автоматическое обновление тега @author в коде при регистрации? Вы могли бы , вероятно, достичь этого с помощью SVN-крючка. Например, вы можете перечислить всех разработчиков, которые изменили данный файл в том порядке, в котором они его изменили; или кто его больше всего изменил; или что-то еще. Или, если @author указан в (исходном) коде, который вы выпустите во внешний мир, вы можете рассмотреть возможность добавления @author автоматически как часть сборки релиза (я подозреваю, что вы можете получить эту информацию из SVN каким-то образом).

Что касается добавления более одного уровня @author тега (или другого комментария), я бы сказал, что вы накапливаете много бесполезного шума. (Опять же, у вас есть SVN.)

По моему опыту гораздо полезнее идентифицировать историческое изменение (скажем, изменение строки кода или метод), а затем определить, какое изменение устанавливает это (и какой билет трека). Затем у вас есть полный контекст для изменения: у вас есть билет, набор изменений, вы можете найти другие смены изменений в одном и том же билете или примерно в то же время, вы можете найти связанные билеты, и вы можете увидеть ВСЕ изменения, которые сформировали эту единицу работы. Вы никогда не получите это от комментариев или комментариев в коде.

Answer 2

У вас может быть более одного знака @author. Если вы внесете некоторые большие изменения в класс, просто добавьте новый тег @author с вашим собственным именем. Нет необходимости отмечать сделанные вами изменения или помещать свое имя вокруг изменений, поскольку история изменений должна быть в состоянии четко отображать это.

Answer 3

Возможно, вы захотите рассмотреть , почему вы хотите получить теги автора в источнике. У Apache Foundation нет, и я согласен.

http://www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags

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

Answer 4

В действительно больших и длительных проектах с большим количеством разработчиков полезно знать, что ho отвечает за данный код, который может предоставить вам дополнительную информацию и тому подобное. В этом случае было бы удобно иметь такую ​​информацию в файле, используя тег @author. Не отметить, кто создал файл или внес какие-то крупные взносы, но кто является контактным лицом для этого кода. Это могут быть разные люди, поскольку автор-автор может быть уже по разному проекту или покинул компанию несколько лет назад.

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

Решение, которое может работать, не должно содержать @author для каждого файла, но только для каждого модуля (пакеты высокого уровня). В Javadoc есть функция, где вы можете документировать не только файлы, но и целые пакеты (See this question for more detail).

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