Back to General and Gameplay Programming

Commenting code - completely useless?

General and Gameplay Programming Programming

Started by jtrask January 31, 2007 12:26 PM

86 comments, last by Tachikoma 17 years, 1 month ago

OrangyTang

1,298

February 01, 2007 03:04 PM

Comments really wind me up sometimes, especially when I often come across things like:

/// SomeClass::SomeMethodName/// parameters:///   int foo///   int bar/// return:///   boolbool SomeClass::SomeMethodName(int foo, int bar)

I just end up reading through it and thinking "well, duh". Six or so extra lines of comments which convery zero extra information than just looking at the function signiture directly. And the signiture is guranteed to be correct.

I've got into the habit of deleting these if I'm changing something in the function. I suspect it annoys some of my co-workers - sooner or later someone is going to come up to me and say "You removed all the comments in my class!". But I'd rather have concice code rather than stuff it full of noise. Plus then theres a greater likelyhood someone will think that it's light on comments and actually add some useful ones.

[size="1"][[size="1"]TriangularPixels.com[size="1"]] [[size="1"]Rescue Squad[size="1"]] [[size="1"]Snowman Village[size="1"]] [[size="1"]Growth Spurt[size="1"]]

tstrimp

1,798

February 01, 2007 03:23 PM

Quote:Original post by OrangyTang
Comments really wind me up sometimes, especially when I often come across things like:
/// SomeClass::SomeMethodName/// parameters:///   int foo///   int bar/// return:///   boolbool SomeClass::SomeMethodName(int foo, int bar)
I just end up reading through it and thinking "well, duh". Six or so extra lines of comments which convery zero extra information than just looking at the function signiture directly. And the signiture is guranteed to be correct.

I've got into the habit of deleting these if I'm changing something in the function. I suspect it annoys some of my co-workers - sooner or later someone is going to come up to me and say "You removed all the comments in my class!". But I'd rather have concice code rather than stuff it full of noise. Plus then theres a greater likelyhood someone will think that it's light on comments and actually add some useful ones.

I agree, usualy. Unless there is some more information reguarding the parameters or the return value then it's useless just to list them. If you're returning a pointer to something for example it can be handy to let them know what it's returning if the function fails, etc.

Washu

7,836

February 01, 2007 04:46 PM

Quote:Original post by LessBread
Quote:Original post by Washu
Quote:Original post by LessBread
Go back and look at some code you wrote two years ago but didn't bother to comment on and get back to me... [smile]

Why did you write it that way and not some other way? Why did you call that API and not some other one? What were you thinking at the time? What tidbit of information did you find that led you to use the approach you used?

God help the poor sucker that ends up having to maintain uncommented code. Pray that it's never you.

Funny, I've gone back and looked at code of mine from over five years ago...its as readable now as it was then, but narry a comment in sight.

I've read other peoples code that was written in a clean and readable manner, without a comment in sight. Guess what, its just as readable now as it was then.

Decent tests usually demonstrate why a particular decisions was made, and even if that is not available, you should be keeping a log of the design decisions you've made. If you aren't, then you're an idiot.

Comments are rarely needed, except as a means of clarifying what might be a particularily complex operation that has resisted clarification through refactoring. The myth that code without comments is unreadable is just that, a myth. People who perpetuate that myth tend to write bad code, which explains why they need so many comments.

Write clean, well refactored code, and you'll find that comments are no longer needed except for that rare case.

I guess you're lucky then.

Lucky? No. Years of experience has led me to believe that luck has little to do with it. You either learn to write good code, or you're a crappy programmer. Unfortunately, the latter outnumber the former by a fairly huge margin. That does not mean you should surrender and join them. Comments tend to, in my experience and opinion, increase with the suckiness of the programmer. They tend to comment more because they can't understand what they are typing. Perhaps if they spent more time thinking before they wrote, they might find that their programs were easier to maintain and read, requiring fewer comments. Note that you usually find other uglies along with comments, such as name warts! As if intellisense wasn't good enough, now we've got to decorate our names to tell us what the hell they are! Attempts at documenting the interface of external libraries, because it obviously was too complex to just reference the person to the documentation.

I've run into some pretty horrible code in my time. Written by people who were dedicated enough to write plenty of comments, but not dedicated enough to bother writing decent clean code. You see, comments are about as hard to maintain as code. Any time you go back and change something in the code, the comments must also be updated. You've just created a point of duplication. At the same time, you've also doubled the amount of effort that you have to go through every time you need to change something. Something that is a clear violation of OCP, a rule that I try really hard to not violate.

[Edited by - Washu on February 2, 2007 9:46:27 AM]

In time the project grows, the ignorance of its devs it shows, with many a convoluted function, it plunges into deep compunction, the price of failure is high, Washu's mirth is nigh.

LessBread

1,415

February 01, 2007 07:42 PM

Quote:Original post by Washu
Quote:Original post by LessBread
Quote:Original post by Washu
Quote:Original post by LessBread
Go back and look at some code you wrote two years ago but didn't bother to comment on and get back to me... [smile]

Why did you write it that way and not some other way? Why did you call that API and not some other one? What were you thinking at the time? What tidbit of information did you find that led you to use the approach you used?

God help the poor sucker that ends up having to maintain uncommented code. Pray that it's never you.

Funny, I've gone back and looked at code of mine from over five years ago...its as readable now as it was then, but narry a comment in sight.

I've read other peoples code that was written in a clean and readable manner, without a comment in sight. Guess what, its just as readable now as it was then.

Decent tests usually demonstrate why a particular decisions was made, and even if that is not available, you should be keeping a log of the design decisions you've made. If you aren't, then you're an idiot.

Comments are rarely needed, except as a means of clarifying what might be a particularily complex operation that has resisted clarification through refactoring. The myth that code without comments is unreadable is just that, a myth. People who perpetuate that myth tend to write bad code, which explains why they need so many comments.

Write clean, well refactored code, and you'll find that comments are no longer needed except for that rare case.

I guess you're lucky then.

Lucky? No. Years of experience has led me to believe that luck has little to do with it. You either learn to write good code, or you're a crappy programmer. Unfortunately, the latter outnumber the former by a fairly huge margin. That does not mean you should surrender and join them. Comments tend to, in my experience and opinion, increase the suckiness of the programmer. They tend to comment more because they can't understand what they are typing. Perhaps if they spent more time thinking before they wrote, they might find that their programs were easier to maintain and read, requiring fewer comments. Note that you usually find other uglies along with comments, such as name warts! As if intellisense wasn't good enough, now we've got to decorate our names to tell us what the hell they are! Attempts at documenting the interface of external libraries, because it obviously was too complex to just reference the person to the documentation.

I've run into some pretty horrible code in my time. Written by people who were dedicated enough to write plenty of comments, but not dedicated enough to bother writing decent clean code. You see, comments are about as hard to maintain as code. Any time you go back and change something in the code, the comments must also be updated. You've just created a point of duplication. At the same time, you've also doubled the amount of effort that you have to go through every time you need to change something. Something that is a clear violation of OCP, a rule that I try really hard to not violate.

I meant lucky in the sense of never having to deal with crappy uncommented code - although it seems now that you haven't been so lucky. I've never seen your code so I can't speak to your coding skills. I'll take your word for it.

"I thought what I'd do was, I'd pretend I was one of those deaf-mutes." - the Laughing Man

OrangyTang

1,298

February 01, 2007 07:48 PM

Quote:Original post by tstrimp
Quote:Original post by OrangyTang
Comments really wind me up sometimes, especially when I often come across things like:
/// SomeClass::SomeMethodName/// parameters:///   int foo///   int bar/// return:///   boolbool SomeClass::SomeMethodName(int foo, int bar)
I just end up reading through it and thinking "well, duh". Six or so extra lines of comments which convery zero extra information than just looking at the function signiture directly. And the signiture is guranteed to be correct.

I've got into the habit of deleting these if I'm changing something in the function. I suspect it annoys some of my co-workers - sooner or later someone is going to come up to me and say "You removed all the comments in my class!". But I'd rather have concice code rather than stuff it full of noise. Plus then theres a greater likelyhood someone will think that it's light on comments and actually add some useful ones.
I agree, usualy. Unless there is some more information reguarding the parameters or the return value then it's useless just to list them. If you're returning a pointer to something for example it can be handy to let them know what it's returning if the function fails, etc.

Oh if theres actual descriptions next to the params then I'll leave them alone, but there almost never is. It feels like commenting just for the sake of it, rather than actually putting in any effort.

[size="1"][[size="1"]TriangularPixels.com[size="1"]] [[size="1"]Rescue Squad[size="1"]] [[size="1"]Snowman Village[size="1"]] [[size="1"]Growth Spurt[size="1"]]

Timkin

864

February 01, 2007 08:27 PM

The general rule of thumb I use (and I teach this to my students) is don't write comments stating what you did (because that's obvious if someone takes the time to read the code), write comments about why you did it when it is not obvious from the code. An obvious example is when you've modified a standard algorithm. Your code block might have a brief reference at the top to a source for that standard algorithm (for instance a published paper), then within your code you note specifically and succinctly the change and why. This will inform anyone later that the deviation was intended and not a bug.

Comments don't *have* to be beside or above the code, unless it's a brief comment that clearly and succinctly conveys the why and is only really relevant here. Comments, if you feel they are necessary, should be located at the earliest place in the code that someone reading it would be required to know it to understand the code.

Washu, you claim design logs do this, but you're still stuck with the duplication of information that you claim to avoid by not commenting... it's just that now your duplication is across two files, rather than local to the code.

While in an ideal world comments might not be needed, even the best coders still screw up, or do things that are simply wrong (because they're human and still make poor choices which, with hindsight, need to be changed). Thus, comments assist those poor suckers who have to come along later and clean up the mess to reach their goal sooner. If that means they need to spend a small amount of time updating the comments, this small overhead is worth it for the time it will save the next sucker that has to maintain the code.

Remember, no code is EVER perfect.

Bracket

240

February 01, 2007 08:58 PM

When working in a team on a large project, I tend to (and encourage my minions!) comment heavily - before I write any code at all. When mapping out an architecture, a series of comments in important methods map out at a very high level what that function will do when someone gets around to writing it. A stub then either returns a mock value (for use elsewhere during development), or throws a NotImplementedException. The great thing here is that when one of the team gets to actual implementation, the intent is obvious - and can be factored out into small methods easily. We often keep the original comments around, as well as using them as a skeleton for development.

The downside of this is that sometimes a method will appear to have relatively redundant comments - beautifully written code that spells out in detail what the high-level description says. That's a bit of a waste of space, but it has turned out to have one really, really nice upside: when we are showing new programmers around the code-base, they can see how we progress from architecture, stubs and then specifics. (it's also nice to be able to open up the SVN history for a file, and see it progress from stub with comments to implementation - you can learn a lot from that!)

Incidentally, I think I first came across this idea in Code Complete.

Edited because I missed a sentence.

romer

323

February 01, 2007 10:36 PM

While I can understand the stance that self-documenting code that's well written is usually sufficient to convey information to a programmer, I still tend to comment a fair amount for the simple reason that when I'm quickly scanning through code either I or my co-workers have written, I can read and understand a blurb of natural language in a comment faster than a piece of self-documented code. Does this mean every line has a comment? No, but distinct blocks will just have a quick one liner saying at a high level what's going on so that it can be quickly scanned. Good, bad, or indifferent, I find this just helps increase productivity for me, so I call that a win for me.

And I also disagree that comment-heavy code is a reflection of a shoddy programmer. There are some domains where you can write clean, relatively clear code, but you still can't grasp at a high level what the big picture is. For example, my latest project involved writing a library that normalizes a variety of acoustic signals my lab processes. I'd like to think the code is well written and clear enough to read through, but I still added a large number of comments so that someone who's never seen either the code or the algorithm can get a high level idea of how the signals are being transformed each step of the way.

In general, I write comments in such a way that a future maintainer who has no prior knowledge of the procedures and algorithms used by our lab can just pick up the codebase after I'm no longer working there, peruse through the comments, and have a pretty darn good and unambigious understanding of what's going on.

davepermen

1,047

February 01, 2007 10:55 PM

code should be written in a way that it's self documenting and selfcommenting and needs no "green text" at all.

and _then_ you should write comments, but only where needed to describe something. like for example the quadratic formula solving function above, where, in the title, you have the original equation in a comment, so that it's visible. so if anyone is unsure what's the quadratic formula about, he sees it.

comments should never be about the how, but about the why. or the what.

i have nearly no comments in my code, but it's still readable after some years (tried and succeeded). the only things that aren't clear sometimes anymore are the why's and what's. but, at least since my move to c#, even that is most the time completely clear.

i think it has to be about the level you code in as well. in c#, where you code in fairly high level, commenting isn't really that needed. but if you look at the c-example above, which is very lowlevel, comments are really needed to explain the 'how' actually.

code should not have comments and be understandable. comments are there for the certain cases where it isn't.

If that's not the help you're after then you're going to have to explain the problem better than what you have. - joanusdmentia

My Page davepermen.net | My Music on Bandcamp and on Soundcloud

Telastyn

3,778

February 01, 2007 11:06 PM

I make it a practice to always comment code changes caused by bugs. If someone did something once to cause a bug, there's a good chance they'll "fix" your code to re-implement it if you don't warn them.

-- Tangent Developer Journal - Delegates - Part 2

Commenting code - completely useless?

This topic is closed to new replies.

Popular Topics

Recommended Tutorials

Commenting code - completely useless?

This topic is closed to new replies.

Popular Topics

Recommended Tutorials

Reticulating splines