接口的 Javadoc 注释？

Question

我正在自学 Java，并希望得到有关此问题的反馈：编写一个具有两种方法的 Java 接口，一种将两个双精度加在一起返回总和，另一种将两个双精度相乘返回乘积。使用 JavaDoc 注释。

我错过了什么吗？在接口的 JavaDoc 注释中包含 @return 是否合适？

/**

 * 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 没有任何根本性的错误或“缺失”。在接口的 JavaDoc 注释中包含 @return 是否合适？这是绝对合适的。接口是 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.