• ### Announcements

#### Archived

This topic is now archived and is closed to further replies.

# good commenting:

## Recommended Posts

Hi, Maybe this question isn''t that appropriate in this forum, but I dare try to post it anyway Can anyone give me some good examples of how to comment code? I mean, suppose you have a large method that you want to comment (algorithm steps...), how can you make a comment that is easily read and "flows" with the code. Not line-comments. I mean overview-type-comments. One example is:
  void method(blabla) { // Use runge-kutta int a=0; ... // This is a "nested" comment int a=0; runge++; .. //end of runge-kutta } 
A better alternative might be:
  void method(blabla) { // USE RUNGE-KUTTA int a=0; ... // This is a "nested" comment int a=0; runge++; .. //end of runge-kutta } 
Maybe alternative 2 is easier to skim through. Note that alt2 treats comments almost as for/if loops that indent their bodies. Any opinions? /Mankind gave birth to God.

#### Share this post

##### Share on other sites
Well, for one you shouldn''t have functions that are so big they require tons of comments strewn throughout. I personally am a big fan of writing small, concise functions and document those functions.

However, when a paticular group of lines deserves special attention, I use your first method. Seems like all that extra indenting will make it harder to tell where there are actual loops or conditionals.

Some people also prefer this style:

  void foo (){ cout << "in foo" << endl; // Prints "in foo"}

"If consquences dictate our course of action, it doesn''t matter what''s right, it''s only wrong if you get caught."
- Tool

#### Share this post

##### Share on other sites
What I comment

I use this before all functions
//////////////////////////////////////////////////////////
//
// Function:
//
// Description:
//
// Parameters:
//
// Returns:
//
//////////////////////////////////////////////////////////

The end of the function
All of the variables and what they are used for
The end of large if statements, switch statements, and loops
Conditions
Formulas
Logic comments(what the code is doing now, I like doing this in block form)

Don’t forget white space.

#### Share this post

##### Share on other sites
I feel that functions should be commented well throughout.

Chances are when you come back to that code, you''ll not remember how it works when you visit it again in several months. It''s even more important when you work with a team of people. They don''t know what you were thinking when you coded something, so you have to explain it in the comments.

If you want to make more "overall" comments inside a function, I know I do, just choose a different way of commenting so that it stands out from the rest.

Perhaps something like

/*
Initialise
*/

// Perform first step of initialisation

Of course this like most things in programming, is just a matter of preference.

- Pete

#### Share this post

##### Share on other sites
to Wayfarer:
But if you use the first alternative, do you use capitals or something like that?
// RUNGE-KUTTA
...
// nested comment

or maybe
// R U N G E - K U T T A
...
// nested comment

or even
// ------Runge-kutta
...
// nested comment

/Mankind gave birth to God.

Edited by - silvren on October 19, 2001 4:22:21 PM

#### Share this post

##### Share on other sites
Personally I start all comments in column 1 and put blank lines before and after them. I feel it helps seperate them from the code. I''m either interested in reading the comments or in reading the code at any particular time and not interested in reading both at the same time. If you comment as you say I don''t really see the point to the indentation. What you describe is not pseudo-code comments. I use a style that clearly deliniates phases of a function so that might make a differance.

#### Share this post

##### Share on other sites
If I ever were in the middle of one function needed to do Runge-Kutta, there would definetly be a RungeKutta(...) function called.

The comments should tell you something the code doesn't. i.e. don't say "use runge-kutta", say "Solve for first point of contact". Yuo may just happen to be using RK in a collision solver, you'll always be looking for the first point of contact.

Edited by - Magmai Kai Holmlor on October 20, 2001 1:26:58 PM

#### Share this post

##### Share on other sites
quote:
Original post by silvren
to Wayfarer:
But if you use the first alternative, do you use capitals or something like that?
// RUNGE-KUTTA
...
// nested comment

or maybe
// R U N G E - K U T T A
...
// nested comment

or even
// ------Runge-kutta
...
// nested comment

I agree with Magmai. I''m especially pre-disposed to writing many small functions since I''m a Java convert and calling out into functions in Java is actually more efficient than loading one big one on to the stack (go figure).

Here is a little explanation of the Wayfarer coding:
So I''ve got some prliminary ideas jotted down, I''ve got Dia (which rules) open in the background with some OO diagrams of whatever I happen to be making. For me, coding a function involved first writing a java-style doc-comment (which is similar to what the AP posted, but a little more structured). My description is an english-language version of exactly what the method does and what effects it has on the members of that object. Then, when I open up the .cpp file to write the body of the method, I watch for when I start to do things like you mentioned, when certain groups of lines begin to take on their own personality seperate from the function their in (like your example). It''s this point in time when the .h file is opened back up and another function is added to the interface.

Of course when and how you do this is generally a matter of taste, writing small, modular functions clears up the readability of code enormously.

As for comment style:
  /** Method Name * Description * Preconditions * Postcontidions * @param param1 the first parameter * @param param2 the second parameter * @return return value */ int CWhatever::method_name (int param1, int param2) { return param1 + param2; }

I generally try to avoid things like massive indentations, dashes, all-caps, and putting spaces between all the letters of a comment I want to stand out. Alhtough it makes it easier to spot, it slows down the speed I type and genrally just becomes a hassle of a convention to stick with.

"If consquences dictate our course of action, it doesn''t matter what''s right, it''s only wrong if you get caught."
- Tool

#### Share this post

##### Share on other sites
ok, thanks.

One problem I see when using "javadoc"-packing of comments just before the methods is that they take quite much time to write (macros helps a lot), but also to fill them.
I mean, there''s A LOT info that one can pack in every method (dependencies,exceptions,pre/postconds,params,assumes,version,author,hides,overrides...)!

Man, that''s much to write and more importantly, much to update!
Also, that info can be much more than the actual code.

Therefore I wonder, do companies use much documenting in the actual code? Isn''t it a pain to update those comments?
Isn''t it better to have good UMLs for domain-models, design-models, interaction-diagrams etc? Coz, if one uses those things, is there really any need to use exhaustive commenting?

Any opinions appreciated!

/Mankind gave birth to God.

#### Share this post

##### Share on other sites
quote:
Original post by silvren
Therefore I wonder, do companies use much documenting in the actual code? Isn''t it a pain to update those comments?
Isn''t it better to have good UMLs for domain-models, design-models, interaction-diagrams etc? Coz, if one uses those things, is there really any need to use exhaustive commenting?

Heh, at my company (a small internet company of approx 30 people) we wish we had time to document as much as we wanted, but alas deadlines loom and with the internet economy in such bad shape most clients don''t really want to pay for extra documentation.

UML diagrams are definately good to have, but having the code & the documentation in the same file is really helpful. If you''re dillegent about updating comments when you change code you shouldn''t have any problems (although incorrect comments are worse than none at all). I just find it easier to keep one file in sync with itself rather than two or more files in sync with each other.

What''s really important is finding a style that makes it easy for you to read, write, & understand. Go over to SourceForge and look at some source code. Find a few styles that you like and make your own hybrid.

"So crucify the ego, before it''s far too late. To leave behind this place so negative and blind and cynical, and you will come to find that we are all one mind. Capable of all that''s imagined and all conceivable."
- Tool

#### Share this post

##### Share on other sites
I''d say 30% of the code documentation where I work is wrong. I''ve learned to ignore it - consequentially I feel it''s largely a waste of my time to write it. The more tedious it is to update, the more likely it won''t be done, and thus it becomes damaging instead of useful.

Code documentation seems redundant and useless to me - unless you''re trying to sell your library. For instance the Win32 API would be pretty hard to use with the MSDN library. But if it''s for internal use, I prescribe to the ''extreme programming'' philosophy that there should be a living document. Why spend a massive amount of time writing and maintaining detailed documentation to communicate to the cube next-door? just tell them!

The thing that always irritates me about software documentation is that it''s always about the details, sometimes about the big-picture, and never gives you the complete story.

#### Share this post

##### Share on other sites
magmai:

But well-illustrating UML-s ought to be quite good then.
Reverse-engineering can help to update some diagrams quickly.

Another quick question:
Do many find hungarian-notation useful? Yep, it''s easy to see for example that a variable is a member and a long, but in my opinion it "contaminates" the code and hides the overall picture. When one is examining for example an algorithm, you usually don''t need to know that a variable is a long etc.
What''s more, it takes some time to put m''s and lpz'' etc.

Any opinions?

/Mankind gave birth to God.

#### Share this post

##### Share on other sites
I recommend reading the Java coding standard by Sun - I follow most of it from C++ too. Javadoc is good because I can use doxygen to do stuff with it. I don''t always do all the params and returns unless I have tools to do it for me. I only see benefit in that when you are developing an API to give the doc away, then I try to do it on all of them.

I agree functions should be small enough that you rarely need to putt // comments in there, except to explain unusual things, or other things not immediately clear.

Function block comments describe the "function", (duh!) and class block comments describe the usage of the class in as much detail as possible.

The final piece of the puzzle is a good, up to date design document and UML model. That''s where you need the most words.

Do as I say, not as I do

~~~
Cheers!
Brett Porter
PortaLib3D : A portable 3D game/demo libary for OpenGL
Community Service Announcement: Read How to ask questions the smart way before posting!

#### Share this post

##### Share on other sites
HN is very useful for native types, not so useful for object instances. I use the m_, s_, g_, ms_ pre-fixes and use a _ post-fix for parameters. Being able to look at a variable and instantly know it''s type and life-time saves aweful lot of hunt&peck time. I use p for pointers and h for handles as well. I mentioned this in another thread, consider this common equation:
  //You have no idea if this is correct or not - it probably compiles, but it might not produce the expected result//Nor do you know how long any of these value/results last//Nor do you know how efficent it isdistance = velocity * time;//You instantly recongize that this is very very wrong.//You instantly know the scope of the damage//You instantly know it could be more efficentdDistance_m = m_fVelocity_kph * dwElapased_ms_;//And in that instance you save the Uranus lander from becoming a freezing heap of scrap

It''s called code for a reason. It''s not supposed to be easy-to-read it''s supposed to efficently and un-ambiguously describe an algorithm or process - that''s what readable code should mean.

#### Share this post

##### Share on other sites
If I would use different SI-units in a program I think I would use Unit-classes for that, and implement appropriate methods, so that I can ignore the units altogether.
If performance must be high, I wouldn''t use different units at all.
If you still want different units, then your approach seems to be appropriate.

Anyway, can you give me some examples of good HN, with explanations?

/Mankind gave birth to God.