May 19, 2005
An interesting article on Writing comments
Mike Clark has written an interesting article at Sticky Minds titled "Write Sweet-Smelling Comments", that raises a topic that I've always liked to discuss about.
I don't like to see many comments in my code, because I tend to find them disturbing. I prefer to use good naming schemes for properties and methods, to write code that speaks by itself more than writing a lot of comments.
I don't remember where I heard it first, maybe it was a manager in a previous job, but I believe that if your code needs to be commented, you should refactor it.
Of course, if you want to generate a javadoc-style documentation from your code, that's different, but, anyway, that's something I've never done.
Here's the link to the article again ( found via The Server Side )
Posted by Cesar Tardaguila Date: May 19, 2005 10:26 PM | TrackBacksorry ot disagree but what's wrong with the humble comment?
while I like to write code so it'll read (almost) like english (it's the old VB programmer in me wanting to get out) saying that code should be refactored because it has some comments in it almost sounds like snobbery.
a quick case in point:
<.cfif not structKeyExists(URL, "uid")
or not structKeyExists(URL, "mode")
or url.mode eq "add"
or len(url.uid) EQ 0 .>
you look at that and go "WTF???" and sure it takes 10 seconds to work out why the IF is needed but if you add a quick comment:
<.!--- tidy up to make sure the url arguments will return a new blank record ---.>
the comprehention time is now zero seconds. That's why I add comments (and lots of them) - to tell at a glance exactly what's going on and spend no time at all trying to work out what the code is doing. It's something taught to me when I was a student and something I passed on in many years teaching programming to newbies.
and how about (straight from a CFC I worked on last week):
<.!--- NOTE: for future developers: this xml repository idea is still a new concept for this module (ie: a quick and dirty hack). If you're looking at this code for ideas to do something similar for other entities consider creating a new XML Entity package, refactor this into it by modifing the code to accept entity_type (and remove this stuff) ---.>
surely there's nothing wrong with doing either of these?
my 2c
barry.b
aggree with barry - sounds like your old bos what a snob.
Comments are a nercessity - theres been several times I've inherrited stuff that is uncommented and its a nightmare to get your head around.
Now whilst overuse of comments is bad thing - there is no need to write a thesiis in the head of the code - I think it's a fundemental requirement
Posted by: pete en: May 20, 2005 02:32 PMbugger!
the code snips didn't come out in that last comment. no matter. I'm sure people can work out where I'm comming from...
Posted by: barry.b en: May 20, 2005 04:52 PMSorry, Barry, I've just fixed the html in your comments to show your code.
Regarding the comments, well, I've seen things like:
//loop the array to extract....
for( i=0; i< theArray.length; i++ )
{
}
That's something that I believe should be avoided.
When you inherit code, sure, some comments will help, but I think that a document that briefly explains what the code is supposed to do will be more helpful. Or a brief comment explaining what a class does and its relation with other entities. So, instead of this:
/*
* method
* returns true when the user is loged
*/
I'll prefer to see something like
function userIsLoged( ): Boolean
Anyway, I guess every developer will have his own preferences, but I like these discussions so much...
