5 ms·
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
by kodablah 13y ago
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.
- nollidge 13y agoYeah, 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.
- AnimalMuppet 13y agoYes... 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.
- nollidge 13y agoAgree 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
- benjaminpv 13y agoSeconded. 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 13y agoThat pisses me off but the following is much worse. The commit comment that goes: "checked in abstract_class.cpp" Duh!
- lmm 13y agoI 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 13y agoI sincerely hope that you and I never work on the same project =(
- lomnakkus 13y agoJust 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 13y agoYes, 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 13y agoAlways 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.