I use Checkstyle (Google Checks) in Eclipse, and for every Javadoc tag, the compiler shows the warning "Javadoc tag should be preceded with an empty line" even though there is one. The only way to remove the warning is to introduce an HTML line break balise.

For example:

     /**
   * shows drinks units in fridge.
   * 
   * @return amount of drinks in fridge.
   */

The compiler will give a warning "Javadoc tag '@return' should be preceded with an empty line".

Of course it's possible to deactivate the warning in Checkstyle, however I still would like to know why the compiler does that. My teacher and classmates do not have that warning even without a line break balise, and they have no idea why I have it, and on the sourceforge page of Checkstyle (https://checkstyle.sourceforge.io/apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/RequireEmptyLineBeforeBlockTagGroupCheck.html) , HTML balises are also not required.

Thanks for your help !

CodePudding user response：

Check the exact bytes at that position. There's probably an actual character up there, such as a non-breaking-space; word processors commonly 'fancy up' your inputs and turn them into weird characters. For example, if you paste "hello" into word and then back into java it is no longer a string constant because word decided to turn them into curly quotes: “hello” which isn't java. That same strategy can be used to sneak non-breaking spaces and the like in there. The vast majority of blank unicode characters count as whitespace, but the checkstyle plugin may be broken in this regard (it would only consider space and tab as irrelevant). Alternatively, checkstyle may be requiring a space after the * on the empty line, so that the full set of characters on that line is \t * (tab, space, star, space).

But most of all...

your process is broken. You have a style checker and you're now focussing on something that is utterly irrelevant, but your javadoc is horrible.

You have a method presumably named countDrinksInFridge(), and you 'documented' this method with javadoc that gives you completely useless non-info, and does it twice, to boot! There's a reason DRY is a near universally agreed upon fantastic tenet in programming, and you just violated it. twice, no less.

The fact that a style checker is whining about which exact kind of space character you used but thinks it is perfectly peachy to write boneheaded javadoc should be proof enough that it's clearly not doing what it's supposed to.

Good documentation rules are as follows. They are all based on a simple idea: Documentation should be maintained, maintenance isn't free, and documentation is hard to impossible to test, so any errors in them tend to hang around for a long time before someone realizes it is wrong. Just like in writing code, if you have needlessly taken 10 lines to code something that could have been done just as efficiently in 2, you've messed up. The same applies to documentation. Do not repeat yourself, do not provide pointless or redundant information. Say it clearly and say it succintly.

• If you have nothing more to add because the method name exactly describes the entire nature of a method, then do not document it. The method name IS documentation. Let it stand on its own.

• If you do have something to add but describing what it returns fully covers it, then just write the @return tag. This is fine:

/**
 * @return amount of drinks in the fridge.
 */
public int countDrinks() { ... ... }

The only reason you have javadoc here at all is because someone decided that mentioning 'in the fridge' is worth it. Of course, this is still bad code style:

class Fridge {
    /**
     * @return The amount of drinks in the fridge.
     */
    public int countDrinks() { ...... }
}

It's bad because 'in the fridge' is not useful information here. Duh, of course in the fridge. It's in a class named Fridge. Think about it: Give me the odds that a programmer is confused about what Fridge's countDrinks method does, but the javadoc @return The amount of drinks in the fridge. clears it all up for them. Surely, those odds are 0%, and that's not even rounded down.

The lesson is: Processes to guard against bad code style, hard to maintain code, and other such style guide-adjacent ideas is something you can't fix with just software and rule packages. It's the business of humans: You work on in-team training, your hiring practices, code review processes, a general culture that one should care about code's objective qualities and not get hung up on over-forced measurements such as 'does the codebase pass some style-checker ruleset?', and only after you have all that established, then you can think about getting some software to lightly aid you in accomplishing the needs of the team.