over commenting

Absolutely! Comments should provide either an abstraction which summarizes what the code does (higher level view) or extreme detail if something really tricky is being done.

In my own work, I try to document every non trivial function, and to put a comment every 10-20 lines which explains what is getting done and WHY at a high level.

After walking into a several meg code base and trying to work out the flow, it is definitely important to have both high level documentation in code AND documentation on what entire systems handle.

I think assembly is OK to comment heavily but that''s it. The problem with comments is they disrupt the flow of the code when reading it -- a simple algorithm can look complicated if you insert comments around various places. The exception is comments that are at the end of the line, like NeHe''s comments. Those are OK if you indent them out of the way.

~CGameProgrammer( );
DevImg.net - Post screenshots, comment on others.
Town 3D Engine - A city-rendering 3D engine. Download the demo.


// Below I explain my intentions.
// The idea is that sometimes I say things that others
// don''t understand.
I''m going to start commenting what I say around here, because
obviously there are many who don''t know what I''m talking about
When I speak.
// End of statement.


___________________________________

"The outside of a horse is good for the inside of a man" - Winston Churchill

It depends on what you are working on at the time, but usually, I would think just enough commenting to enhance the readability and make maintaining it easier. Well, unless specified otherwise, for one CS class I am in, I have to comment in what Big O my algorithm is, and prove it somehow... warning, following is in java...

public int maxCon2(int[] x){
  int maxSoFar=0; //O(1) constant time
  for(int  i = 0; i < x.length; i++){  //O(n)
      int sum = 0;
      for(int k = i; k < x.length;k++){ //O(n)
        sum+=x[k];
      if(sum>maxSoFar)
         maxSoFar=sum;
      }
    }
} //Function is O(n^2)... or something like that...
  

yea.. I generally don't comment much at all, except for a program header and if I don't understand the concept fully, I will give myself a clue as to what it is supposed to do.

[edited by - bastard2k5 on April 20, 2003 1:57:18 PM]

My programming teacher makes me comment every single little thing, from curly braces to declarations. It is really quite annoying...

 int function( int x )
{ // Begin function
     // Declarations
     char choice;

     // Prompt user
     cout << "Enter choice:";
     cin >> choice;  // Get letter from keyboard

     // Enter for loop
     for( int y = 0; y <= x; y++ )
     { // Begin for
          // Display numbers
          cout << y;
     } // End for

     // See what choice the user picked
     if( choice == ''A'' )
     { // Begin if
          cout << "You chose the first letter in the alphabet";
     } // End if
} // End function  

quote:

---

Original post by circlesoft
My programming teacher makes me comment every single little thing, from curly braces to declarations. It is really quite annoying...

 int function( int x )
{ // Begin function
     // Declarations
     char choice;

     // Prompt user
     cout << "Enter choice:";
     cin >> choice;  // Get letter from keyboard

     // Enter for loop
     for( int y = 0; y <= x; y++ )
     { // Begin for
          // Display numbers
          cout << y;
     } // End for

     // See what choice the user picked
     if( choice == ''A'' )
     { // Begin if
          cout << "You chose the first letter in the alphabet";
     } // End if
} // End function   

---

I have a CS teacher who demands excessive comments. The only thing it really accomplishes is convincing the students that comments are ALL dumb and useless, which causes them to undercomment, or discard the practice altogether.

I openly broke her rule one day by writing a program to go through all of my source files and remove all the comments and whitespace. The look on her face was priceless.

its very possible. it is dam annoying reading 2 paragraphs of comments then you see 1-3 lines of code then another paragrah then another inline function, then 3 more paragraphs maybe if your lucky you will finally get to the 50 lines of variable definitions.

There are people who have quota rules.. which I can't stand.. quotas in general seem like a bad idea to me, I vote we ban all quotas ever made. People who say stuff like "1 comment every 3 lines" end up with code like this:




They comment the wrong lines.. not realizing that lines like
gamma2 -= i ? epsilon/i : theta != pnz ? qwerty(pnz) : theta;
could use some commenting, but instead insert useless comments.

After you write a small chunk of code, maybe one line.. maybe one class depending on what type of stuff you're writing, you should glance over it and see what isn't obvious.. and rewrite it to be more clear and/or comment it to explain.

[edited by - cozman on April 20, 2003 10:33:02 PM]

I have a professor who said he worked at a place once upon a time where they recommended 7 comments PER LINE OF CODE. Eeek!

int/*this is going to be an integer fucntion*/ function/*function is the function name*/(/*this is the beginning of the parameters for the function "function"*/int/*integer is the first parameter type*/ age /*age is the name of the variable that will be used in the function*/)/*end of parameters*/{/*beginning of the function right here*/while/*while loop*/(/*while loop parameter is here*/age/*we are using age as the parameter*/)/*end of parameters for the while loop*/{/*beginning of the while loop definition*/age=1/*set age to one*/}/*end of while loop*/}/*end of function "function"*/


thats how i comment my code, is that too much?

No, you need 7 comments per line of code. Maybe you could add in what kind of ''int'' you are working with, and what other kinds of ''int'' you might be working with on other architectures. Example:

int/*this is going to be an integer function. an ''int'' in this case is a 32-bit value on my machine at home, but at work we have itaniums, so an ''int'' at work is a 64-bit value. i also have this old DOS machine in my closet, and if i ran my program on it, for some unknown reason, then an ''int'' could be 16-bits, but i''m not really sure, because sometimes i think an ''int'' can be 32-bits in dos. in assembly language, ''int'' stands for ''interupt''. that isn''t what we are talking about here, because this isn''t assembly language. this is C! C is a good programming language, because it has portable ''int'' types so you don''t have to worry about how big the word size is on any machine. you just write your code and it should work! unless of course you need 32-bit ''int'' but you run it on a DOS machine in your closet. but who really wants to play on their computer in a closet?*/

Here''s a much more descriptive and readable version:

comments IN the code are counterproductive i think, i hate reading code that has a line of code and a line of comment mixed. if its tabbed over to the right, on the same line, it makes it so you can read through the code and if you find something you don''t know, just look to the right and read the comment. that way, if you don''t need the comments, you don''t have to have them get in the way

i always put my comments on the left, like this:

//ok this is the start of the function: int function(int x) {
//this is the first line of the function: while(x>0){x--}
//this is the return value: return x;
//this is the end of the function: }

but for some reason my code never works, so i came here and i just got flamed so now i code with variables and html

I too code c++ in html using variables and cache, but the internet explorer html interpreter doesn''t run my code. it just displays it, which I assume means, "hey, there were errors on these lines", and so i go eat cookies instead.

quote:

---

Original post by bishop_pass

// Below I explain my intentions.
// The idea is that sometimes I say things that others
// don''t understand.
I''m going to start commenting what I say around here, because
obviously there are many who don''t know what I''m talking about
When I speak.
// End of statement.


___________________________________

"The outside of a horse is good for the inside of a man" - Winston Churchill

---

LOL

---

Current project: A puzzle game.
% completed: ~0%
Status: Active.

quote:

---

Original post by circlesoft

 int function( int x )
{ // Begin function
     // Declarations
     char choice;

     // Prompt user
     cout << "Enter choice:";
     cin >> choice;  // Get letter from keyboard

     // Enter for loop
     for( int y = 0; y <= x; y++ )
     { // Begin for
          // Display numbers
          cout << y;
     } // End for

     // See what choice the user picked
     if( choice == 'A' )
     { // Begin if
          cout << "You chose the first letter in the alphabet";
     } // End if
} // End function    

---

I don't find this commenting too bad. There are some parts that are unecessary (like "begin if", "end if"), and there are some parts that say nothing ("enter for loop"). Here's how i would do it:

 int function( int x ) {    
     
     char choice;

     // Prompt user
     cout << "Enter choice:";
     cin >> choice;

     // iterate, printing the index of each iteration (?!)
     for( int y = 0; y <= x; y++ ) {
          cout << y;
     }

     // Print the choice the user picked
     if( choice == 'A' ) { 
          cout << "You chose the first letter in the alphabet";
     } 

}   

I think this is great for "scanning" the code, i can easily understand (and find )the parts of your code, without necesseraly having to look at the code.

Victor.



[edited by - -vic- on April 20, 2003 11:32:58 PM]

quote:

---

Original post by Russell
No, you need 7 comments per line of code. Maybe you could add in what kind of ''int'' you are working with, and what other kinds of ''int'' you might be working with on other architectures. Example:

int/*this is going to be an integer function. an ''int'' in this case is a 32-bit value on my machine at home, but at work we have itaniums, so an ''int'' at work is a 64-bit value. i also have this old DOS machine in my closet, and if i ran my program .....

---

HA!

-vic-: that''s even too much commenting for me, if it makes sense I let it be.

anyways I didn''t know anyone else was pro enough to program in Variables html. I''m still learning it