# Commenting Method

This topic is 4919 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

## Recommended Posts

I was just wondering what everyones take is on the most understandable commenting methods for functions and classes? I'm going to be adopting a style and have no idea which one to use.

##### Share on other sites
Generally the best method to use is one that a automatic documentation builder will understand. For example java's javadoc system or Natural Docs.

##### Share on other sites
most important rule: comment what the code does, not how it does it....

good comment :

// sum all ages
for(unsigned i=0;i!=nm;++i)
total += values;

bad comment (tells me nothing that i couldn't determine from the code) :

// for each value, add to total
for(unsigned i=0;i!=nm;++i)
total += values;

as mentioned, commenting headers using javadoc, doc++ or doxygen comments is a damn good idea. I use doxygen personally....

##### Share on other sites
I find that I've conformed to Visual Studio's XML documentation for library documention creation via NDoc.

##### Share on other sites
Writing comments is the easy part.

The hard part is keeping them accurate/relevant as code is changed and bugs fixed and introduced.

I'd take an innane correct comment over a well-thought-out, well-formatted and beautifully articulated incorrect or outdated one.

##### Share on other sites
Quote:
 Original post by ajas95Writing comments is the easy part. The hard part is keeping them accurate/relevant as code is changed and bugs fixed and introduced.
Agreed, not what you're doing, but why.

##### Share on other sites
Quote:
 Original post by RobTheBlokemost important rule: comment what the code does, not how it does it....

I would like to make an addendum to that: comment why the code does what it does in cases where it might be unclear (for example, lots of convoluted math).

##### Share on other sites
You could take a look a literate programming. Its fairly extreme.

I think it takes jack Reeves' 1992 ARTICLE to heart; the code is the design not the product.

##### Share on other sites
I'm pretty flexible in this area. Here's the general layout I use. At the start of every header file (but not associated inline or source files), I have a comment block like the following:

/*--------------------------------------Node-------------------------------------------*\ |||                                           Created 6/1/2005	Last Modified 3/8/2005\*--------------------------------------Node-------------------------------------------*/

It's exactly 90 columns wide so it prints nicely. The contents of my comment blocks don't have many fixed requirements at this stage, though I'm going to develop this area somewhat. In this case, it's empty, though at some stage, ideally information should be filled in giving some kind of basic description of the class, what kind of role it fils, and how it fits into the rest of the system if applicable. I do not try and explain absolutely everything in these comment blocks. That's what seperate support documentation is for. It should give enough information so the programmer knows what documentation to consult if he needs to learn more.

Inside the class body, I organise the functions into logical collections, and put a little comment above them indicating the name of the collection, which should basically sum up what those functions manage. Eg:

//Constructors	inline Node();	explicit inline Node(const String& aName);	Node(Stream& stream, const ChunkHeader& header, const Resource::Group& resources);	virtual ~Node();

Inside a matching source or inline file for this class, everything is grouped in a way that corresponds to the grouping in the class body. The start of each group is indicated by the following comment block:

/***********************************Constructors****************************************/

If desired, the programmer can extend this down and fill in some information about the block, however it is optional. Each function is then preceeded by its own comment block, which looks like so:

//---------------------------------------------------------------------------------------

Every function has this line above it. For functions that the programmer feels requires further explination (which really should be most of them), the comment block can be extended, and text added in the middle, like so:

//---------------------------------------------------------------------------------------// Sets the name the node to the specified string.//---------------------------------------------------------------------------------------void Node::SetName(const String& aName){	name = aName;}

In current versions of Visual Studio, this comment block also works with the tooltip popups in intellisence, to display this comment block when you have it selected. Eg:

And I've just noticed I missed a word in that comment, but whatever. This comment block ideally should describe exactly what that function does, as well as briefly explain the arguments and return type, and any relevant effects calling this function will have on the public state of the object. It again is just a brief explination, and a full, more detailed description is left to external documentation.

Within functions, there are no restrictions on comments whatsoever. The programmer is free to place them wherever he feels they are nessicary. No block comments (/*...*/) are allowed within function bodies however, unless they are there to comment out blocks of code during development.

##### Share on other sites
Quote:
 Original post by RobTheBlokemost important rule: comment what the code does, not how it does it....good comment :// sum all agesfor(unsigned i=0;i!=nm;++i) total += values;bad comment (tells me nothing that i couldn't determine from the code) :// for each value, add to totalfor(unsigned i=0;i!=nm;++i) total += values;as mentioned, commenting headers using javadoc, doc++ or doxygen comments is a damn good idea. I use doxygen personally....

I would say the good comment is a bad comment too. It should be replaced with more descriptive variable names, or even encapsulated within its own function.

int SumAges(int Ages[], int NumberOfAges){int SumOfAges = 0;for(unsigned int AgeIterator =0; AgeIterator < NumberOfAges; ++AgeIterator  )  SumOfAges += Ages[AgeIterator ];return SumOfAges;}

Now you have a functionality which can be used anywhere in your code without duplication, and have also removed the need for a comment. Your code now simply becomes

void function(){....int SumOfAllAges = SumAges(Ages, NumberOfAges);}

Which is pretty self commenting.

• ### What is your GameDev Story?

In 2019 we are celebrating 20 years of GameDev.net! Share your GameDev Story with us.

• 9
• 34
• 16
• 11
• 12
• ### Forum Statistics

• Total Topics
634123
• Total Posts
3015649
×