Programmers: How well do you comment your code?

[AmigaMan]

I comment depending on if there is paper documentation for the code or not. If not, then most likely I am doing a code fix and I intersperse comments in the code. Especially if it is an algorithim I'm writing. If there is sufficient specs and documentation, then my comments are sparse and only where neccessary.
I also find that when starting a project, I comment a whole lot just to help during debugging. After I'm sure the code works, I tend to take most of the stupid comments out and leave what I think a programmer coming in after me (to maintain the code) would want to see.

 

[cavingjan]

I comment at the beginning of a function and if I insert code from another source, I comment just prior to where it begins. I also put in some comments in the middle of a function when I'm switching from one task to another or using a command or API call that I'm not overly familiar with just to remind me later. I do not make that many change comments in the code itself. When I delevelope, that type of commenting goes into a separate word document and when I final the code, they get placed into a bas file (sorry, I use VB for everythign now) and stay there. I hate comments in the middle of code that take up more lines than the code itself. Just date the change and one quick line of comments and move the rest to the bas file please. Also makes it easy to check what changes have been done overall.
Now that I'm back in school taking classes on programming (CIS121 - feels like vb for dummies; already told the prof I was taking this so I could take the advanced class and didn't really expect much out of this: week 3 and we are still only on command buttons and labels ) I see myself at odds with the prof over commenting.

 

[Descartes]

.

 

[Supermercado]

I comment as needed. If it's a simple thing like int <name of variable>; or something, I would usually throw a short comment in to say what the variable is going to be used for. But usually my variables are self-commenting, just as they told as to do back in CPSC 101. Three semesters later I'm in 215 and doing the same thing. Now, once I get to actual body of the code, I don't see it as necessary to comment things like i++; because anyone who has any business reading my code should know what that does. Something more obscure, like an especially slick algorithm to do something that isn't immediately obvious, warrants comment in my opinion. It's just a matter of deciding whether something is so plain as day that doesn't need commenting or something more obscure that does. Now, when I was programming in SPARC assembly language last semester, I commented nearly every line just because the code was so obscure, even though it was performing a simple task like incrementing a variable. In this case, it was more for my benefit, so I could learn the language and actually have a clue as to what I was trying to do.

As I read through the thread, I noticed that someone said that if you're a Computer Science major, all you'll be doing is programming. I asked my advisor this exact question, seeing as how I don't have the desire to write code all day, every day for the rest of my life. I was told that many Computer Science majors don't end up doing nothing but programming. That's all I wanted to hear.

Anyway, it's gotten a wee bit long. Maybe instead of $.02, that oughta be worth $.03 or $.04. Hehehe.

 

[BlueScreenVW]

Here's a site with a "Links and resources" link on the front page. Check it out. http://www.accu.org/

 

[audiophan]

hmm, unless its for a class or something important not much at all. then again i don't write anything very long

 

[darkjester]

I comment pretty much as often as possible when it seems necessary. Of course, I also go for the self-commenting code as much as possible (descriptive error strings, variable names, etc). Heck, even when I'm doing a solo thing, I comment because if I come back to it a few months later, I want to remember what I was doing.

I used to comment a lot more when I was in school, though. I learned early on that TA's that look at dozens of different implementations of one project really need the whole thing spelled out for them or they'll miss a couple of things that might have been worth a couple of extra points. No joke, once I got a 52/50 on a project because my comments/documentation was that good. The code wasn't even that spectacular.

But I've lived and learned and now I'm a sparse commenter, like the rest of the professional programming world.

 

[Maverick]

I'm pretty bad at commenting code. I usually only write comments that help me out when I'm trying to fix bugs. Now I'm working on a year long project that requires us to do everything in Javadoc comments. Needless to say its a huge pain in the ass for me. I've never had to have other people read my code and understand it.

 

[amnesiac]

*piff*
.
.
.
.
.
.
.
*thud*

(sound of amnesiac 2.0's head exploding)

 

[stonecold3169]

It really depends on what I'm writing. Classes I usually comment for my and other people's sanity, esspecially if you start defining classes and then declaring them as different types and the such. For most functions, if at all possible I just pick very descriptive variable names and go with. Granted, sometimes that isn't possible, so you insert a few lines of comments in.

 

[Kntx]

Ususally when I first start writing a program I say "this time it's going to be different" and I comment a lot. But then as the program gets furthur and furthur along, the comments get more and more sparse. Until there are none.

 

[LeStEr]

I comment a little to much as well but what you said seems to be quite reasonable.

 

[im2smrt4u]

I comment like MAD! If I leave a project and come back to it later there is no way I can ever remeber what I was doing without comments! :Q

 

[EagleKeeper]

For those of you who claim that you are the only one who will look at the code.

Baloney, you are to young to be that stupid to believe that.

Quality systems will last from 5-20 years or more.

You will probably be long gone by then from that project and some other poor slob will have to suffer with you ego. Big deal you say.

And then you will get playing CYA for a egotistical slob before you.

Try to maintain and understand assembly code or any other massive project written without documentation; both code and manuals.

Go back and review something that you have not touched for 6 months and determine if you understand what everything is supposed to be doing and interacting with each other and the external world.

 

[Sir Fredrick]

<< Go back and review something that you have not touched for 6 months and determine if you understand what everything is supposed to be doing and interacting with each other and the external world. >>



That's the key right there.

My current project contains nearly 4000 lines of code that I have written, and I'm probably halfway done. I don't care how well written this stuff is, it's a monster and I wouldn't expect everyone to immediately understand what's going on (especially since I sometimes do things in a way that is slightly less clear in order to improve execution time and/or reduce memory usage), and if I have to work on this project 6 months later, sure I'll be able to figure out what everything is doing again, but it will take a lot longer without the documentation.

Oh yeah, and when I was a TA, students lost a lot of points for having poorly commented code.

 

[cyclistca]

I only comment code that's tricky. Plus I use very descriptive variable names. I do business programming so that's usually plenty.

 

[Mookow]

<< I comment too much >>



What? once?