Friday, August 29, 2008

Tired of writing nonsense javadoc / xml-comments?

Getting Real is about skipping all the stuff that represents real and actually building the real thing.

-- 37signals

I can't make up my mind if writing javadoc (or xml-comments in .NET) is falling in the above category ... but often I have the feeling it is preventing me from getting real.

Very often it just doesn't generate any additional value. Usually JSF-Backing-Beans are a good example for this: In most cases the comment does add exactly nothing compared to the property name...

/**
* Get the name
* @return name
*/
public String getName(){
...
}
People from the department of redundancy department would be delighted ... the DRY-gang just left the building ...

images.jpg I do not want to dispute that sometimes comments are absolutely necessary. But I don't think that it is a good solution to rigorously require comments on everything, just to catch the few spots that need them...

... thats like requiring that everybody wears a helmet at work!

Nevertheless in most projects this is the case... as a consequence the quality of the comments is mostly bad and nobody reads them...
But writing them costs many hours and even can give reason for passing or failing a milestone including the the whole traffic on the escalation-ladder ... bummer!

At least there are some tools that can outomate this nonsense (even though this results in an excuse for not getting real!):
  • JAutodoc for Eclipse
  • GhostDoc for Visual Studio
  • 1 comment:

    1. I think we all can choose to write javadoc (most of the time they say we must, but we can). I write javadoc only if I feel that is needed. However if you are forced to write javadoc those tools are great.

      ReplyDelete

    Related Posts Plugin for WordPress, Blogger...