Управление исходным кодом делает Javadoc @author и @since избыточным?

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

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

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

Ответ 1

Я думаю, что тег @author фактически путает вещи. Прежде всего, если он не обновляется разумно, он становится неправильным. Кроме того, что, если вы (не будучи оригинальным автором) меняете половину класса? Вы обновляете @author? Вы добавляете его? А что, если вы измените только несколько строк в классе?

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

Наконец, как вы сказали, такая же информация, более подробно, доступна из вашего VCS. Все, что вы добавляете в Javadoc, - это дублирование. И дублирование - это плохо, верно?

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

Ответ 2

Хорошо, во-первых, видимость Javadoc обычно превосходит видимость управления версиями. Я могу просмотреть библиотеку Javadocs для Java 1.1, но не могу, насколько мне известно, свободно просматривать историю версий Sun с тех пор.

Вы говорите так, как будто ваши Javadocs полностью изолированы от вас (разработчик) и не распространяются среди других как часть API и т.д. Это не всегда так. Как правило, информация Javadocs и VCS выполняет совершенно разные цели.

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

Ответ 3

Я знаю, что мы использовали их, и они действительно приятны, просто просматривая исходный код. У меня было более одной ситуации, когда @since было очень удобно иметь там, так как потребовалось бы немного работы, чтобы определить, какая версия была добавлена (путем сравнения дат и т.д.).

Только мой опыт. Я думаю, что @author был менее полезен, но поскольку мы можем автогенерировать обе части данных при создании новых классов, это не похоже на то, чтобы просто позволить системе сделать это со мной.

Ответ 4

Нет. Аудитория страниц javadoc может не иметь доступа к вашему источнику, поэтому эта информация имеет значение.

@since важна, поскольку с документацией можно ознакомиться в более старых версиях программного обеспечения. Когда вы увидите, когда была введена функция, вы знаете: 1) что она недоступна для вас, и 2) что есть хорошая причина для обновления.

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

Ответ 5

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