Summary
Perhaps bad and nonexistent documentation is to be expected -- there isn't even agreement that it is important.

Perhaps bad and nonexistent documentation is to be expected. Ever seen good code comments in a book? Ever heard a programmer being praised for well commented code? The best you can hope for is a smattering of mind-numblingly dull and ridiculously incomplete Word documents that are a year or more out of date.

We are used to the culture of making others dig thru the dirt. It is considered a badge of honor to decipher how a piece of code works and should be used. There was a time when such things were interesting to me, but now I'm tired of the cat and mouse game.

The GTSL* argument is that the code is the documentation. Unfortunately, the code is not the truth. It is full of lies, deceit and broken promises. Looking at the code, it is quite easy to follow the wrong path.

I guess I shouldn't be too surprised or dismayed by this; after all, is good commenting taught in schools? Are there any books on the subject? Even books that talk about programming style often let you off the hook by saying that it is even more important the code should have meaningful variable and method names than thorough comments. I think this is often interpreted as "comments are not important." Even for those few who make a concerted effort to have meaningful variable and method names, comments are still important. Unfortunately, many people don't even do that, yet still assume the comments are unnecessary.

The only place I have ever seen reasonably well-commented code is in professional APIs and components. Despite complaints about Java API documentation or Windows API documentation, at least there is some.

How can we instill some sense of responsibility to write clear and well-commented code in the average programmer?

* Grep the Source, Luke!

Talk Back!

Have an opinion? Readers have already posted 20 comments about this weblog entry. Why not add yours?

RSS Feed

If you'd like to be notified whenever Matt Gerrans adds a new entry to his weblog, subscribe to his RSS feed.

Digg | del.icio.us | Reddit

About the Blogger

Matt Gerrans is Artima.com's C# columnist. Matt began his professional life as an electronic engineer but quickly saw the light and switched to software development. He now has more than 12 years professional software development under his belt, including work in C++, Java, Python, and yes, even JavaScript.