How to be Specific enough in writing javadoc

问题

I have question related to writing standard javadoc comments. They ask us to be as specific as possible and use predicates to describe the code, but if I have a variable "d" written in my comment, but not indicated in my code, would that pose a problem?

Once again, I ask this question because I get confused and my teacher is strict on commenting code.

/**
 * 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);
}

回答1:

To write the documentation you have to put yourself in the role of the person that uses your method. As a user of your method I don't care if you fly to the moon and ask an alien for the result as long as I get reliable the correct result.

So normally implementation details should not be included into the documentation (if you have a variable with the name "d" in your implementation should not matter to your documentation). You should be able to refactor or change internal details without it affecting your documentation.

Examples for exceptions are facts that affect:

behaviour (i.e. thread safety)
performance (one could argue that flying to the moon would affect the performance ;) )
security
...

So what does interest the user?

what the method does - the user likely has not the same knowledge as you so explain a lot (for example not every one knows what a GCD is)
what parameters are expected, what they are and how they should look like (in your example its important that the numbers are positive and whole numbers, in your case "a" and "b" may be 0 - but not every definition of the GCD has 0 as a valid value included)
what can I expect to be returned, what is returned in border cases (like a and b =0)
what exceptions do I need to expect and when are they thrown

So a documentation for your method could look like:

    /**
     * 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 );
    }

来源：https://stackoverflow.com/questions/35902263/how-to-be-specific-enough-in-writing-javadoc

标签

javadoc

code-comments