How many comments?

[Windwhistles]

How many comments do you write in your programs? I probably write a few more comments than necessary.

[ModShop]

Enough so that I can go back to something later on and be able to figure out how it works without spending too much time reading code. The more complex code I'm writing, the more comments I have.

[Owain]

Often I dont write any because I have a good memory for my previous thought processes, but if I am writing code for someone else then I like to be safe and write quite alot.

[Catfish2]

As few as possible, as many as needed.

[3hM2Nwbp]

In my source files, there are absolutely no comments whatsoever. If your source code needs comments for people to use your API, something is very wrong. My header files on the other hand are documented using a doxygen compliant format with much information including a detailed description of what the method does, preconditions, postconditions, parameters, parameter defaults, exceptions, thread safety, links to other areas of interest, and when applicable, example usage.

[abo0ody]

I think it depends on whether you are making an API that needs to be documented or a one file program for a puzzle or an excersise, however COMMENTS DONT HURT so I always try to comment each and every thought, function or even every line if its needed

[ResidentBiscuit]

I don't write library or API code so, I can't comment there. I'd imagine a lot more comments would go in there.

Usually, I'll put a comment at the top of my class header files giving a brief outline of what it does, and then comment on non trivial methods explaining the parameters, return value, and the purpose of the method.

Everyline is way too much. If i look at code that has too many comments, it's actually detrimental IMO. Seems to make it less readable, and there likely isn't a need to comment every line. I assume most people can look at a function with an idea of what it does, and then see how it's implemented by themselves.

[LB]

If you have to write comments to understand your code later, your code is BAD. I believe in writing obvious code for which writing comments would be redundant. I only leave comments to remind me of things I have yet to do.

[Duthomhas]

I disagree. Within internal code you should still provide commentary in order to maintain the higher-level abstraction (i.e. meaning) of your code, and to explain choices in algorithm.

That code should be clear is not orthogonal to proper commentary -- one describes the details of how something is done -- the other describes what is being done and design choices made in its implementation -- as well as give pointers for further reading for technical material.

[3hM2Nwbp]

@Duoas

I completely agree with your stance on commentaries on internal technical details, yet I don't feel that scattered notes within the source code is good enough. I usually compile a collection of diagrams and articles in a clean, concise format independent of the source code to act as a guide to future codebase maintainers.

[Stewbond]

I see this fairly often in the code at work and I HATE it. I swear it must have been a coding standard at one time, but I hate it.

/*******************************************************/
/*                                                     */
/* Function call: max                                  */
/*                                                     */
/* Number of Arguments: 2                              */
/*                                                     */
/* Argument list:                                      */
/*     int number1 -- The first number to be compared  */
/*     int number2 -- The second number to be compared */
/*                                                     */
/* Return value: The maximum of number1 and number2.   */
/*                                                     */
/* Return type: int                                    */
/*                                                     */
/*******************************************************/

int max ( int number1, int number2 )
{   

    return ( number1 > number2 ) ? number1 : number2 ;  // return

} // end function max



/*******************************************************/
/*                                                     */
/* Function call: min                                  */
/*                                                     */
/* Number of Arguments: 2                              */
/*                                                     */
/* Argument list:                                      */
/*     int number1 -- The first number to be compared  */
/*     int number2 -- The second number to be compared */
/*                                                     */
/* Return value: The minimum of number1 and number2.   */
/*                                                     */
/* Return type: int                                    */
/*                                                     */
/*******************************************************/

int min ( int number1, int number2 )
{   

    return ( number1 < number2 ) ? number1 : number2 ;  // return  
	
} // end function min 

On the otherhand, I also disagree with L B. Overusing comments is bad, but I like to put info from my reference schematics or system requirements in there.

Also, since I work with a lot of bad programmers (we're engineers, not comp-sci people) I do like to add comments on some of the more complicated syntax so that someone doesn't re-write it because they can't understand it.

[Ikaron]

@Stewbond:

You seriously have to put up with that? xD The only line I would find useful in that would be what the return value represents. Maybe the argument list in some cases, but I feel at that point you'd be better just giving a description of the function.

[3hM2Nwbp]

This is the kind of documentation that I'd expect for a 'max' function.

http://gcc.gnu.org/onlinedocs/libstdc++/libstdc++-api-4.6/a01187.html#gaacf2fd7d602b70d56279425df06bd02c


...although I cannot help but criticize

This does what you think it does.

Feels a little bit sloppy.

[firedraco]

...although I cannot help but criticize
>This does what you think it does.

In one of my CS courses we had a teacher who required all functions be commented with what they do, so half of my functions with obvious names had that as a comment. :P

[Cheraphy]

I literally never comment unless it's to comment out a block of code while I test something else. This is bad practice and I'm trying to get in the habit of fixing that.

[S6k9GNh0]

When I write something, I comment the reason for the code, the reason for the design behind the code, and how to use the code (if applicable). I also give very strict definitions on how the code is supposed to "react" so I or someone else can realize if something is malfunctioning.

I often write more comments than I do code.

[Duthomhas]

@Luc Lieber
It depends on your work environment and any documentation requirements. I am of the school that the further away from the code that the documentation is, the less maintained it is.

There exist numerous systems to handle it, including those that allow you to modify documentation and related code at the same time (rare), to those that extract documentation from source code (common), to dedicated documentation writing personnel (sadly common), to just telling programmers to update a specific documentation database (also sadly common).

@Stewbond
You left out the "Modified By" and "Last Modified" and "Project Name" and "Satisfies Requirement" fields.

That kind of boilerplate nonsense is common in the industry, alas. Management puts it there to encourage stupid programmers to properly document their code and how they modify the system. What usually happens is that every function in a module has the exact same header from someone who quit years ago.

If you have to put up with that kind of stuff, perhaps a demonstration of the negative impact of that kind of verbiage on compile time and maintenance.

This does what you think it does.

Elephant. I think that it returns whichever value is greater than a global variable somewhere. I think that the GNU folks ought to be ashamed of that one.

Here is an example of one of my comments in a very simple project:
http://www.cplusplus.com/forum/lounge/74394/#msg402102
For more advance projects, the commentary will be a little better organized, but otherwise eschew useless information.

I don't claim my method is superior to any other, but I personally like it. :O)

[Windwhistles]

I usually divide my code into blocks with comments at the top. Also sometimes instead of adding a comment, I will just add a line. I think it looks more concise that way, too many comments can make the code harder to read.

int main()
{
	double length;		//cube length
	double width;		//cube width
	double height;		//cube height

	//get cube dimentions
	cout<<"Enter length:  ";
	cin>>length;

	cout<<"Enter width:  ";
	cin>>width;

	cout<<"Enter height:  ";
	cin>>height;

	//print cube volume
	cout<<"\nVolume: "<<length*width*height;

	return 0;
}

[3hM2Nwbp]

Oh my...(on the same track as GCC's ambiguous docs)

http://docs.oracle.com/javase/7/docs/api/java/nio/charset/CoderMalfunctionError.html

</off-topic>

I've been doing quite a bit of Java work lately. Maybe I'm catching the madness.

:)

[Duthomhas]

I never rely on comments to tell me what a name should.

Either one of the following suffices:

int main()
{
	double cube_length;
	double cube_width;
	double cube_height;

	//get cube dimentions
	cout<<"Enter cube length:  ";
	cin>>cube_length;

	cout<<"Enter cube width:  ";
	cin>>cube_width;

	cout<<"Enter cube height:  ";
	cin>>cube_height;

	//print cube volume
	cout<<"\nVolume: "<<(cube_length*cube_width*cube_height);

	return 0;
}

// All this stuff is to calculate the VOLUME of a CUBE
int main()
{
	double length;
	double width;
	double height;

	cout<<"This program calculates the volume of a cube.\n";

	//get cube dimentions
	cout<<"Enter length:  ";
	cin>>length;

	cout<<"Enter width:  ";
	cin>>width;

	cout<<"Enter height:  ";
	cin>>height;

	//print cube volume
	cout<<"\nVolume: "<<(length*width*height);

	return 0;
}

(These are just two variations... there are many more, but these demonstrate all the important aspects.)