4 ms·

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

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.

bananas 12y ago
That pisses me off but the following is much worse. The commit comment that goes: "checked in abstract_class.cpp" Duh!
- lmm 12y ago
  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.
  - MBlume 12y ago
    I sincerely hope that you and I never work on the same project =(
  - lomnakkus 12y ago
    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.)
    - sbilstein 12y ago
      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.
    - lmm 12y ago
      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.
tieTYT 12y ago
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.
lomnakkus 12y ago
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.
levosmetalo 12y ago
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.

bananas 12y ago

That pisses me off but the following is much worse. The commit comment that goes: "checked in abstract_class.cpp" Duh!

lmm 12y ago
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.
- MBlume 12y ago
  I sincerely hope that you and I never work on the same project =(
- lomnakkus 12y ago
  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.)
  - sbilstein 12y ago
    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.
  - lmm 12y ago
    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.

tieTYT 12y ago

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.

lomnakkus 12y ago

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.

levosmetalo 12y ago

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.