Документирование метода, который просто возвращает что-то

Question

Я пишу несколько javadocs (на самом деле это jsdocs, но это не имеет значения для этого вопроса) и нашел этот повторяющийся шаблон:

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

public long getTimeSinceTheEpoch(){

  //calculate time

  return time;
}

Пока все хорошо. Теперь, когда приходит время добавлять javadocs (или jsdocs, или rdocs, что угодно), я пишу что-то вроде этого:

/**
* Gets the time in milliseconds since the unix epoch
*
* @returns the time in milliseconds since the unix epoch
*/
public long getTimeSinceTheEpoch(){

Здесь проблема очевидна.

Мой вопрос: что вы помещаете в текст комментария и что вы выбираете для атрибута @returns комментария?

ВАЖНО

Я не фанат подобных комментариев, если бы это зависело от меня, я бы переименовал метод в что-то вроде getTimeInMillisecondsSinceTheEpoch и вообще избегал комментариев.

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

Answer 1

Лучше всего предоставить только описание @return, поскольку вам необходимо точно задокументировать, что вы возвращаете.

В разделе комментариев вы также можете добавить одну и ту же строку, но также добавить как вы собираетесь возвращать то, что возвращаете, например,

/**
* Gets the time in milliseconds since the unix epoch
* by doing something incredible.
* /2423212/dokumentirovanie-metoda-kotoryi-prosto-vozvraschaet-chto-to
*
* @note thank you stackoverflow
*
* @returns the time in milliseconds since the unix epoch
*/
public long getTimeSinceTheEpoch(){

Answer 2

Руководство по стилю Sun (теперь Oracle) " Как писать комментарии к документу для инструмента Javadoc " рекомендует следующее:

Тег @return необходим для каждого метода, которыйвозвращает что-то отличное от void, даже если это избыточно с описанием метода.(По возможности, найдите что-то не избыточное (в идеале, более конкретное), чтобы использовать его для комментария тега.)

Мне не нравится избыточность, и это идет вразрез с DRY принцип.Лично я либо делаю одно резюме, а другое - подробно (как предложено выше), либо предоставляю только @return.Как вы указали, в качестве сводки может быть достаточно имени простого получателя.