What are your intentions?
Listen to this article
Allow me to vent for just a minute. I promise it won't take long...
In an effort to improve the amount of Javadoc in the source base, the current project I'm working on has been set up (not by me I might add) to use checkstyle to enforce Javadoc standards.
Following on from why javabeans are evil I have to say that enforcing Javadoc on getters and setters (that's accessors and mutators for all you Java Certified Developers out there :-P) is one of the most pointless things I've ever seen.
It takes me about 10 seconds to use IntelliJ (or eclipse for that matter) to generate all the getters and setters for the attributes on my DTOs. It then takes me ten minutes to either write the JavaDoc by hand. So I try using the auto generated javadoc only to find that it takes almost as long to change all the generated Obtains the value of paymentDate to Obtains the value of the payment date.
In fact it occurs to me that if my IDE can work out what to generate as javadoc, surely I can work out what the code is doing simply by looking at it?
I've always been a fan of commenting code. I guess it comes from my assembler programming days. I must admit I write fewer and fewer comments these days as my programming style has changed to be more "self-documenting". No matter what though, if you are going to write comments, it's important that you document the intent and not the implementation. How many times have I seen this:
++i; // Increment the current index collection.add(values[i]); // Add the value at the current index to the collection
This serves no purpose other than to satisfy the good-old comment/source-code ratio checker :-). Even worse, it adds nothing to my understanding of the code (ie intent) and IMHO adds significantly to the signal/noise ratio.
Most javadoc I see follows along similar lines. When 50% of the code is comments, kindly informing me that the getCustomer() method Gets the customer, etc. I can't help but wonder what the hell we've been spending our time doing.
What's worse, as with most kinds of heavy documentation, the comments rapidly become out of date as we constantly refactor the code, rename classes, attributes, etc.
Hmmm...I'm no language expert (as is evidenced by my ramblings on this site) but I wonder if it's possible to analyse the comments and determine if they're documenting intent or implementation detail?
In any event, as a start, do me a favour and don't enforce Javadoc on getters and setters. I'll meet you half way and try to get used to putting opening braces on a new line :-)
Comments
Unfortunately, there is no comprehensive theory of javadoc. Still, it never hurts to apply common sense. IMO, javadoc'ing setters is a waste of time unless they 1) do not accept null 2) are not thread-compatible with the class 3) have side-effects (which is dumb in itself). Javadoc'ing getters never hurts because, I guarantee you, there is always confusion as to 1) exactly what a getter _means_ in the domain value 2) whether the getter can return null. In the long run, these two issues inevitably lead to subtle bugs in the code.
Also let me note that the problem here is comments, not javadoc. The problem with comments is that it requires programmers to think. Since programmers are so extraordinarily lazy this isn't good. I've often proposed that there should be a @property (or perhaps @domain tag) tag attached to getters. The value of this tag is in every way equivalent to the 'first definitive sentence of the javadoc'. The difference is that it becomes more like filling out a form (rather than free-form) so that programmers are more likely to write it.
Posted by: Bo | December 14, 2003 08:59 PM
However, wouldn't you agree that documenting variables in code is a good idea? Don't you document "private int id" even though it's still a little silly? So, what you do ;-) is you only document the getter for that property. Then for the property itself, and the setter, you put
"See {@link #getId()}". Perhaps you could get the ide to autogenerate some of this for you. At least, that's my solution to the otherwise redundant and pointless task of documenting all of the property, the getter, and the setter!
Posted by: Will Gayther | December 14, 2003 10:23 PM
Hmm.. you both raise interesting points. I must admit though, I don't tend to document all my private variables. I give them meaningful names and document the few that may still be ambiguous. I agree that if there are special semantics that are not obvious then sure, document that. But i'd say there going to be the exception rather than the rule. Also I do tend to document domain objects a little more heavily than DTOs. But I also put in assertions to check parameters etc. So it's obvious from reading the code what those semantics are. If we're talking about pure documentation thern how about javadoc itself generate them for me? I mean I don't really need them or want them in the code. I guess it wouldn't work in all cases but you get idea?
Posted by: Simon Harris | December 14, 2003 11:28 PM
I think the real enemy here is checkstyle, since it will generate reports of things that really aren't important. It will generate lots of activity from the beginning, while everyone does their best to look good, and during that process it will do more harm than good.
Posted by: Mats Henricson | December 15, 2003 09:46 AM
I think the real enemy here is checkstyle, since it will generate reports of things that really aren't important. It will generate lots of activity from the beginning, while everyone does their best to look good, and during that process it will do more harm than good.
Posted by: Mats Henricson | December 15, 2003 10:18 AM
I'd have to agree with you on that. There are just some checks that I dont think are worth implementing. I've seen method lengths enforced to the detrmiment of the source base too. Prior to the current version, it didn't ignore comments and blank lines when calculating method lengths. In addition, I've seen junior developers simply split methods literally in half just to subvert the checking. YUK! Though to me that's not a problem with the check per-se. More of an issue with experience (or lack thereof).
Posted by: Simon Harris | December 15, 2003 03:56 PM
I completely agree with you. The biggest problem is enforcement. It is not a programmer who is deciding when to write comments but either coding standards (huh....), company policies of IDEs themselves. I think we must understand that there is nothing like coding standards but those are only guidelines.
Posted by: Punit Pandey | January 21, 2004 02:05 AM