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!
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
February 3, 2008 at 11:04 AM
Anonymous 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 :)
February 22, 2008 at 6:15 AM
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
"Good comments, bad code"
3 Comments -
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! ^_^
February 2, 2008 at 2:20 PM
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
February 3, 2008 at 11:04 AM
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 :)
February 22, 2008 at 6:15 AM