如何在编写 javadoc 时足够具体

Question

我有关于编写标准 javadoc cmets 的问题。 他们要求我们尽可能具体并使用谓词来描述代码，但是如果我在注释中写了一个变量“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 );
    }