Commenting code..

The basic rule I follow is, if it takes me longer than ten seconds to figure out what a section of code is doing, it needs a comment. Maintaining code is hard enough without having to waste time reading every line of code just to understand what you're maintaining. I find the best way of "commenting" code is to write code that documents itself. This means using long_descriptive_ variable/function names and using good programming style. I tend to comment as I go while the code is still fresh in my mind but I also reread the code later and if I look at something and go "what the hell did I do there?" then in goes a comment.

All my programs start with a lengthy comment that describes the file, it's function, version, last revision, author(s) and anything else that other coders need to know. All functions are commented with a purpose, pre and post conditions. It's also handy to include the date and person who made a certain revision to a line of code (that's if you're not using CVS or some other similar software). So you know who to blame ;).

I think I would probably go with:

1. If making a public API (i.e. for anyone other than yourself, even if it's only internally to the project!), document each public method / function etc, if using Java, C#, Perl etc (which have their own built-in documentation facility), use that, otherwise create a sensible standard and follow it.

2. Most functions should be small enough that they don't require many comments inline in the code.

3. Any meaty functions,
a. Write the function entirely using pseudo-code
b. Write the proper code and leave the pseduo code in as comments.

4. Call methods, variables etc sensible names if there's any chance they could be confused. using "x" as a local variable in a 5 line function is ok, using x as a global variable or public property isn't !

Anyway it works for me.

Quote:

---

If making a public API (i.e. for anyone other than yourself, even if it's only internally to the project!), document each public method / function etc, if using Java, C#, Perl etc (which have their own built-in documentation facility), use that, otherwise create a sensible standard and follow it.

---

I'm glad this was brought up. We should all be using standards when we write code :).

I usually have more comments then actual code. It makes it a lot easier for your friends to help you debug your code.

I'm terrible when it comes to commenting. I only seem to do it when I am trying to figure something out. If it is some I use often enough, I never comment it.

Quote:

---

I do not add comments, until I get lost in my own code
Then I start to add comments in specific places, like traffic polices...

---

Same here. Except, I usually comment what a specific variable is for and at the start of a particularly long function.

Man, what the heck is commenting code good for? (This is of course my April Fools Joke)

Actually, I rarely comment my own programs (I'm the only one at the office who knows how to write, so they are all 100% my own creation), because I figure...if I can't figure out what it does...then it probably shouldn't be in there.

There was a site out there a few months back (maybe a year, who knows) that had a great joke article on how to make your code so complex that you're the only one who knows what it does...equals job security.

Unfortunately, I generally only comment code when I come back to it a second time to modify somthing. I start looking around, trying to figure out what I had done before, then I comment it as I figure it out. I keep telling myself that I need to start commenting the first time around, but for some reason, I don't listen.

commenting is very easy and should be done as you code.It's like the no: 1 rule of proper
codeing style,you should always comment because at the time while you'r codeing it might
seem to you that everything is understandable but two or three days later that same code wont look
so clear to you ,so always comment your code it makes it easy for you and also makes it easy for anyone that might have to modify your code later on.

crimina1

I dont think i have ever actually use comments in my programs, after all if you program the whole stuff for yourself you really dont need comments except for an occasional one or two or else if you have coded 1000s of lines of complex/confusing statements.

On the otherhand while programming for others esp some new programmer i try to make it as simple as possible by commenting as much as i can.