Topic awaiting preservation: Commenting Code

Being a newbie to coding in general, I thought it best to cover this before I develop bad habits. I need to know approriate general commenting etiquette. When coding, what should I comment? Every little line is obviously repetetive, but I don't want to leave things out. How do you comment?

code-headed intern

Everything what's hard to understand for you would be a good start. In the beginning this willmean you comment every little line. But over time you don't need so many many comments. If you try something experimental comments will be usefull too. The code and it's comments should be readable and understandable if you did not look into it over a year. You can alway strip out the comments when it's compiling time if you want too...

The more professional coders might have some good arguments against many comments but i think comments are good specially while learning something.

------------------------------
Support Justice for Pat Richard

comments per se aren't bad, but they have to be in sync with the actual code...

Usually, when you're feeling you should write a comment, it's a better idea to turn this into a named part, a function, a class, stick a name on it.

Comments as the code goes along (line-by-line/block-by-block) are good. They help explain what's going on, especially in the context of the rest of the system.

What I find lacking, though, are good 'overall' comments. I like to see verbose comments at the top of every class, describing the interface to that class, the methods, what properties are affected by what, what is needed to run that class, why the class exists, what it can (and can't) do,etc. At the top of my classes, I almost always put a 'dreams' list...a list and description of things I'd like to do with the class if I ever had half a second to spare. Maybe give the next guy some inspiration...

I can usually figure out what is happening in the microcosm of line-by-line, or even a single if/then, for, while, or switch block of code.
That bigger picture is way more important to me...and most often neglected.

quote:

---

Comments as the code goes along (line-by-line/block-by-block) are good. They help explain what's going on, especially in the context of the rest of the system.

---

Either completly unnecessary as the code explains all - or the code should be a function with a *name* - even if that's a two line function.

The bigger picture should be explained by the naming and automatic tests - which are always a good start.

TP, I do not disagree with you. Not one bit.

Perhaps my statements could be made more clear by replacing the word 'good' with the pseudo-word 'OK' in that first sentence of mine you quoted. I meant it only as a counterpoint to my next statement. I did not want anyone thinking I was saying short, block-by-block comments were not helpful. Just that the overall picture is, to me, much more important.

Also, seeing my statements as an addendum to what you wrote, rather than a replacement, might clarify what I was trying to say.
Making 'things' named functions and classes goes a huge way towards writing understandable, maintainable code. No doubt.

I gues I'm just a lot less experienced than you are. I still haven't been weaned of human-readable descriptions of what's going on. =)

For me, there's two types of comments :

• the visual guides, which I align to the right and use to repeat the name of a function or class below its delacaration. That way, it's extremely easy to locate the functions/methods even when you scroll like crazy through the source code.
• the "WTF" comments, that explain in few words what does a block of code if it's a bit long and/or that the code is to be read by a co-worker.

Meaninful names of variables and functions almost vanish the need of comments. It's not rare to see a variable/function name exceeding 20 characters in my source codes. Autocompletion is made to be used.

Oh, and one detail : with my settings, the comments appear with a darker background color in UltraEdit. That way they are extremely easy to spot.

"Maybe give the next guy some inspiration."

Mobrul makes a good point. Comments are important for YOU the creator of the code, but if you intend to distribute or share the code extensive comments can really be important to someone who is looking at it completely fresh.

Just from usage I tend to comment using the javadoc format. Usually all functions are declared with the input, output and use. Within functions, if there is something tricky or a some kludgey hack I'll comment that with the thought process behind it. Sometimes for wierd reasons you need to do something "wrong" to get the right results for reasons that are not self evident. These I always comments. I do pretty much the same things for objects explaining input constructors etc as well as the parent class.

As poi pointed out good code, with good variable and function names and standard use of brackets should explain itself.

For large complex projects you get into stuff like UML diagrams where you can have large visual diagrams of the code. I haven't used UML a lot but I've started playing with it a bit for some of my projects.



.:[ Never resist a perfect moment ]:.

The poster has demanded we remove all his contributions, less he takes legal action.
We have done so.
Now Tyberius Prime expects him to start complaining that we removed his 'free speech' since this message will replace all of his posts, past and future.
Don't follow his example - seek real life help first.

quote:

---

bitdamaged said:
For large complex projects you get into stuff like UML diagrams where you can have large visual diagrams of the code. I haven't used UML a lot but I've started playing with it a bit for some of my projects.

---

quote:

---

InI said:
Each function needs a comment header and it has to include the DATE: history logs
are extremely useful to me.

Also, the author: on a project involving several persons, author and date or a full history log
per function is great.

---

In the project I've worked on, each developer was responsible of HIS code and was supposed to be the single person to update it and keep a sort of log in the comments at the top of his files. However, all the developers of the team had an overview of all the gears of the complete project and knew whom to ask for details on a specific area. When I finish a class or a feature, I generally provide an example with it so that the other devs don't even need to open the source of the classes to know how to use them.



(Edited by poi on 07-15-2004 01:23)