Auto Code Commenting Software, Free Chairs

sien writes "When you think about it, code is usually fairly mundane and simple. Finally someone has come up with a parser and lexer that actually auto-comments code, allowing for vastly more rapid coding. This amazing new tool is called The Commentator and claims to analyse source code as it's being written and insert the necessary code comments. It's absolutely amazing. Also the problem of seating for eXtreme Programming has finally been solved."

Comments

OMG LOTF

[sfcat]

This is the first funny article of the day. I like the self-importance option. In truth, a tool like this is impossible to actually write, but it would be cool since I never comment my code. But I don't comment for job security and I hate my coworkers. Just kiddin'

Re:This is becoming tedious.

[Rei]

Perhaps it will be opposite this year? Picking the true article out of the heaps of really bad fakes?

Nice example of poor commenting style

[Kelerain]

Very good humor! But on a more serious note, this is actually part of the problem with some comments. They duplicate the code. Comments like

i++; // increment i by one

really slow down the comprehesion level of most competent programers, because they have to filter out a lot of redundacy. Comment on purpose, on the more general function of things, etc. An automated program, could only really comment on the code that was there, and likely in an obvious way.

Not to detract from the marvelous humor of the 'article' but it was a good demonstration of the problem.

I wish all the software I saw was as well commente

[Software]

I've seen plenty of OSS and proprietary software code that had comments that *looked* auto-generated. Stuff like:

/** Sets the Home to a new value */
public void setHome(String newHome)
{ ...
}

I've never understood why people do things like this. Why not do something useful: specify what's a valid or invalid value of newHome, say when it should or should not be called. Or just leave it blank if you can't find something useful to say.

This comes up in every discussion on comments...

[EvanED]

...and it's just not true.

Good variable names (class names, function names, etc.) go a long way: they tell you a lot about WHAT the program is doing. (I would argue that they can't always say everything too, but that's another matter.)

However, they don't tell you WHY you are doing what you are doing.

Also, remember there are other reasons for comments besides people reading your code. JavaDoc/Doxygen comments allow documentation to be produced right from the source. Comments such as /* FALLTHROUGH */ can tell sourch code analyzers such as Lint some useful information too. (Not to mention the programmer that looks at your code and has to think for a sec "did he mean to leave out the break there?")