One of my opinions these days on javadoc is that you should be minimalist. Have nothing to say about the return type? Don't add @return. Same for @param. Just a sentence about the method/field/class? Just a single line /* * ... */ is fine. Have nothing of value to say on a method/field/class (e.g. a getter), don't add javadoc at all. I'm growing weary of large files with tons of redundant javadoc lines to make some checkstyle/pmd rule happy.
I always bristle when I see javadocs that include things like 'returns an object of [x] type that...' You're dealing with strong types, the signature provides all this information already. That, combined with good variable names, should do a lot of the documentation for you.
If you wanna document a method, document what problem it solves. Document any gotchas (or better yet, redesign them out o_~). Don't just repeat what reading the method's signature already tells me.
Thirded. At my last place of employment I actually made this into an informal[0] coding style rule and succeeded in getting a few people to remove the completely useless default javadoc template which Eclipse (and the like) have for new methods.
One thing I did find very important was to document if your method had any side effects that were not obvious from just its name. (E.g. if a method is called printXXX() or logXXX() you can pretty much guess what it's going to do, but saveXXX() is a little bit more ambiguous. Where is it going to save things? The database? The file system? Is it atomic? Etc.)
[0] I don't believe in formal coding styles (at least not for small teams/orgs) since what constitutes "best" practice is always context-dependent. We handled all knowledge transfer (including coding style) by intra-team code review and a few very high-level documents about the overall system architecture.
Yet, I'm always surprised in how good the official javadoc is at avoiding this problem. They always have a @return and it's usually saying something useful. I think there's two situations:
1) You're writing javadoc for something that isn't really a public facing api. In that case, I agree, remove the @return. Perhaps even remove that / * * and convert it to / *. It shouldn't be officially documented.
2) It is public facing api. It may seem that the @return is redundant, but there's really a better way to document it.
I do that a lot, or rather my commit messages are usually "mumble" or "fixed this" or "awookga". I feel this is more justified than the javadoc case because you can always just leave out javadoc, whereas the VCS forces me to put a commit message.
Just a humble suggestion, but perhaps you should enter a message which states the intent or the functionality of the change more explicitly. (If you're just doing a topic branch, then sure, just say "wip" or "blah", but please clean it up with "git rebase -i" before merging.)
Always topic branches yeah. My team puts that kind of information in the pull request, which ends up playing the role that a commit would in SVN or the like. I guess we could squash our merges to achieve the same effect, but we haven't felt the need yet - the pull request is a nicer interface than a git log.
Yes, even something trivial like "fixes whitespace" is better then nothing, but even better is squashing or amending a previous commit. Some systems prevent this...at my workplace once you've pushed to origin, there is no changing the past so saying something like "Added derp.java to fix broken build from <commit hash>" is very helpful.
I've been guilty of that kind of comments you despise when I had to work in environments where software "quality" metrics were applied to all checked in code as a part of build process and your code was marked as "low quality" because you missed @return document entry in your Javadoc. You can bet that, with few IDE templates to autogenerate all missing JavaDoc on save my metric was quite good. In addition to that, I completely stopped trying to write good docs. What you measure is what you get in the end.
Yes... mostly. I worked with a guy who, for every comment, asked "how can I eliminate the need for this comment?" Usually the answer is to name something better.
But sometimes you really need a comment, not because something is named badly, but because, even with the right name, there's something not obvious about it.
