Self documenting code is a lie

Friday, January 22. 2010

Self documenting code is a lie

Be very, very wary of anyone who suggests that "self documenting" code can replace comments.

Case in point: I consider myself a mediocre programmer, who is usually capable of producing mostly coherent code.

Below is a hunk of the code I wrote today - keywords are blue, variables are white, comments are green:

I don't think I could take much away from that without doing a serious disservice to the poor person (probably me) who will be tasked with fixing the inevitable bugs in the above code.

Posted by David Wolever at 17:51 | Comments (6) | Trackbacks (0)

Trackbacks

Trackback specific URI for this entry

No Trackbacks

Comments

Display comments as (Linear | Threaded)

Wow, that's way overboard!

I must confess that I usually don't comment my code. I know that I should, but I'd never comment as crazily as you did in that blurry screenshot. Is that normal for you?

#1 Daniel Grace (Homepage) on 2010-01-22 18:14 (Reply)

No, that's pretty abnormal. Normally it's either nothing (for small/straight forward functions), a line or two to visually separate the logical parts of a bigger function, and of course the occasional three or four line block where something needs some explanation. Here's the initializer of an ActionScript class: http://img.skitch.com/20100122-tf7e5qpnkyge19r5m11b5ejbkb.png

#1.1 David Wolever (Homepage) on 2010-01-22 18:34 (Reply)

s/weary/wary

#2 Greg Wilson (Homepage) on 2010-01-22 21:16 (Reply)

When this came up in RSS I thought of something else I wanted to say!

I may have uttered something in the past that made you think I said that all code should be self-documenting. I may again in the future.

If so, what I really mean is that self-documenting code is an ideal. And when you hit it, there's little point in documenting it. At the extreme case, getters and (simple) setters do not need a comment.

Many things, usually the things at the heart of the program, need documentation. It's unavoidable. Still get as CLOSE as possible to self-documenting, then document where it wasn't possible.

#3 Daniel Grace (Homepage) on 2010-01-23 03:00 (Reply)

Yes, you're right - clear code (ie, "self documenting") is much, much better than commented ugly code.

But I have heard more than a few people say things along the lines of "I don't need comments because I write self-documenting code"… But, as you've said, there are situations where comments are critical to explain why the line x += 1; x -= 1 is vitally important.

#3.1 David Wolever (Homepage) on 2010-01-23 22:10 (Reply)

"there are situations where comments are critical to explain why the line x += 1; x -= 1 is vitally important."

In many of those cases, changing the name of x eliminates the need to add a comment. E.g. numberOfLinesReadSoFar += 1 or numberOfNewMessages -= 1.

#3.1.1 Ryan Kohn (Homepage) on 2010-01-26 12:22 (Reply)

Add Comment

Name
Email
Homepage
In reply to
Comment	Standard emoticons like :-) and ;-) are converted to images. To prevent automated Bots from commentspamming, please enter the string you see in the image below in the appropriate input box. Your comment will only be submitted if the strings match. Please ensure that your browser supports and accepts cookies, or your comment cannot be verified correctly. Enter the string from the spam-prevention image above: Markdown format allowed You can use [geshi lang=lang_name [,ln={y\|n}]][/geshi] tags to embed source code snippets
	Remember Information? Subscribe to this entry