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.

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

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

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

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.

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

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

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.

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