Search this blog

02 February, 2008

Good comments, bad code

What a good comment is? One that eases the understanding of a block of code.
What a good code is? One that does not requite any comment to be understood.

EDIT: As the brevity of this post seemed to cause some confusion, I'm not advocating the no comments practice. That's only lazyness. Even literate programming for me is nice (but I would not use it in a commercial project), the point is, you should comment every non-trivial issue, and you should code in a way that makes most issues, trivial. (bad) example follows:

// good comment bad code:
assetmanager.loaddata(filename, true); // async load of player mesh

// good code:
assetmanager.load(
playerMeshFile, MODE_ASYNC);

// good code, good comment:
assetmanager.load(
playerMeshFile, MODE_ASYNC); // preloading data in the frontend, as the user has already choosen its player

3 comments:

ugasoft said...

I don't agree, dear deadcode (or deadbeef ^_^)

Obviously self-commenting code is great (and commenting it is a bad habit, comments will go out-of-sync with code at first code change) but there are things you cannot explain without a comment.
For example whenever there are two or more algorithms to do the same thing, a comment should be placed to explain your choiche!

So, dear readers, keep commenting your code! ^_^

DEADC0DE said...

Of course you're right. Mine was just an oversimplification, done to make a point about some wrong habits that you often see like writing "dothis(10, true /* do not overwrite */);" that are really awful

nO0b said...

I still agree with the original post, though. It doesn't say at all "don't comment a clear code" ... rather try to read it more like "if you have more equivalent choices, choose the one that requires the fewer comments".
That still includes commenting why a choice was made, dear ugasoft ;).
That's my opinion, anyway :)