Hacker News Reader

Comment by kodablah | Hacker News Reader

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.

View on HN

Seconded.

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.

That pisses me off but the following is much worse. The commit comment that goes:

"checked in abstract_class.cpp"

Duh!

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 sincerely hope that you and I never work on the same project =(

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.

Yeah, I'm of the opinion that if you need a class/method comment to explain what it takes in or spits out, you probably named it badly.

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.

Agree completely, that's why I said "probably" :)

EDIT: Comments are useful for explaining things like:

1. Non-obvious side effects

2. Code that's working around a bug in a 3rd party library

3. Code that calls into some non-intuitive 3rd party API

4. Citing your work (e.g. "adapted from stackoverflow.com/blah123")

5. Why you used pattern A instead of the more standard pattern B

Reply on news.ycombinator.com