Хорошая практика тегов Javadoc @author

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

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

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

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

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

Ответ 1

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

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

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

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

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

Ответ 2

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

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

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

Ответ 3

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

Ответ 4

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

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

Решение, которое может работать, заключается не в том, чтобы @author для каждого отдельного файла, а только для каждого модуля (пакеты высокого уровня). В Javadoc есть функция, в которой вы можете документировать не только файлы, но и целые пакеты (Подробнее см. Этот вопрос).

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