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.

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

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....

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.

Quote:Original post by RobTheBloke
most 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).

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.

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:



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:



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:



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:



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.

Quote:Original post by RobTheBloke
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....

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.



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



Which is pretty self commenting.