Документация автор тега @передовой практики

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

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

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

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

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

4 53
javascript javadoc authorization

4 ответа:

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

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

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

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

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

52

вы можете рассмотреть почему вы хотите авторские теги в источнике. Фонд Apache этого не делает, и я согласен.

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

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

18

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

8

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

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

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

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

7