如何在编写 javadoc 时足够具体

Question

我有关于编写标准 javadoc 注释的问题。他们要求我们尽可能具体并使用谓词来描述代码，但是如果我在评论中写了一个变量 "d"，但我的代码中没有指出，这会造成问题吗？

再一次，我问这个问题是因为我很困惑，而且我的老师对注释代码很严格。

/**
 * Find the great common divisor between a 2 number.
 *
 * @param a number1 
 * @param b number2
 * @return (\max d; ; a % d == 0 && b % d == 0) 
 **/

public static int GCD(int a, int b) {
    if (b == 0) {
        return a;
    }
    return GCD(b, a % b);
}

Answer 1

要编写文档，您必须将自己置于使用您的方法的人的角色中。作为您方法的用户，我不在乎您是否飞到月球并向外星人询问结果，只要我得到可靠的正确结果即可。

因此通常不应将实现细节包含在文档中（如果您的实现中有一个名称为 "d" 的变量，则对您的文档而言应该无关紧要）。您应该能够重构或更改内部细节而不影响您的文档。

例外的例子是影响的事实：

行为（即线程安全）
性能（有人可能会争辩说飞到月球会影响性能；））
安全
...

那么用户对什么感兴趣？

该方法的作用 - 用户可能不了解您的知识，因此请多多解释（例如，并非每个人都知道 GCD 是什么）
预期的参数是什么，它们是什么以及它们应该是什么样子（在您的示例中重要的是数字是正数和整数，在您的情况下 "a" 和 "b" 可能是0 - 但并非 GCD 的每个定义都包含 0 作为有效值）
我期望返回什么，在边界情况下返回什么（比如 a 和 b =0）
我需要期待哪些异常以及它们何时抛出

因此您的方法的文档可能如下所示：

    /**
     * Returns the greatest common divisor of the two given positive whole numbers. 
     * <p>
     * The greatest common divisor (GCD) is the largest whole number that 
     * is a factor of both of the given numbers. <br>
     * A number is a GCD if it has the following properties: [...] //add the properties here
     * <p>
     * Example: the GCD of 20 and 16 is 4 
     * 
     * @param a
     *            the first positive whole number, may be 0 
     * @param b
     *            the second positive whole number, may be 0
     * @return the greatest common divisor of the given numbers. Returns 0 if a and b are 0. 
     * Returns the not 0 number if one is 0.
     **/

    public static int findGreatCommonDivisor( int a, int b )
    {
        if ( b == 0 )
        {
            return a;
        }
        return findGreatCommonDivisor( b, a % b );
    }

如何在编写 javadoc 时足够具体

How to be Specific enough in writing javadoc

comments

javadoc