Javadoc комментарии для интерфейса?

Question

Я учу себя Java и надеялся получить обратную связь по этому вопросу: написать интерфейс Java с двумя методами, один, который складывает два двойных числа вместе, возвращая сумму, и один, который умножает два двойника вместе, возвращая продукт.Используйте комментарии JavaDoc.

Я что-то упустил?Уместно ли включать @return в комментарий JavaDoc для интерфейса?

/**
 * This is an interface for basic math.
 */
public interface Math {

  /**
   * This method will be used to add two doubles.
   * @param a a value to be added
   * @param b the other value to be added
   * @return the sum of the two doubles
   */
  public double add(double a, double b);

  /**
   * This method will be used to multiply two doubles.
   * @param a a value
   * @param b the other value
   * @return the product of the two doubles
   */
  public double multiply(double a, double b);

}

Answer 1

Я что-то упустил?

Нет ничего принципиально неправильного или "отсутствующего" в javadocs в их нынешнем виде.

Уместно ли включать @return в комментарий JavaDoc для интерфейса?

Это абсолютно уместно.Интерфейс является формой API, а значение значения, возвращаемого методом API, является фундаментальным аспектом интерфейса.Если значение возвращаемого значения метода не указано в интерфейсе, то вызывающий метод интерфейса не может знать, чего ожидать.Это затрудняет программирование интерфейса .

Answer 2

Да, уместно иметь @return.

Несколько вещей, которые вы можете улучшить:

• Чтобы следовать соглашениям Java-кодирования, начинайте имена методов со строчной буквы (например, используйте add вместо Add).
• Имена параметров лучше.Например, используйте number1, number2 вместо a, b.
• Начните описания @param и @return с заглавных букв (например, @param number1 First number).
• Я думаю, что лучше сказать Returns the addition of two given numbers, чем This method will be used to add two doubles.