Как быть достаточно конкретным в написании 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 );
    }