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

Question

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

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

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

Answer 1

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

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

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

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

Answer 2

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

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

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

Answer 3

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

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

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

Answer 4

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

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

Answer 5

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