What are the different standards and practices of code documentation and which have worked best for you?
I ask because myself and friend are starting a company and will probably need to have some agreed upon standard for commenting things so that we can read each other's code more easily.
I would start with a standard for commenting all classes (file name, version control tags for dynamic version/last author/revision history, class purpose) and methods (uses, params, return values) and ensure that all classes and methods are documented in accordence with these standards.
It depends on the language of course, but typically a comment for every method describing what it does, what it requires for input and produces for output are standard. You could also add author name and date if you wish, but it will most likely be apparent in your version control app.
As for other comments, use them sparingly and make sure you describe the why, not the how, when documenting specific lines of code.
Look at what the language "officials" recommend. I'd follow that because chances are that whoever you work with in the future has heard of it as well, or even uses it. I would avoid "inventing" your own standard by all means.
First and foremost, your standard should be that code doesn't need comments -- it should be self-documenting. As different said, comments should explain why you approached a problem in a specific way.
Personally I hate CS101 comments:
int Count = 0; //initialize Count to zero
It's worth remembering that comments are always wrong. This is particularly relevant when you're doing things like writing big function header comments that list all the parameters and the return value and such. You can keep this up for a long time, but eventually as your code base grows, the comment blocks will get out of sync from the actual code. You'll change the name of a parameter, or add a new one, and forget to update the comment. Then the comment is wrong, and therefore useless.
As others have mentioned, your comments should explain why you are doing something, not what you are doing. The what can be answered by reading the code.
Here's what I do. First I comment classes and methods in the header with Doxygen - it helps since I work with Java at home and C++ at work, though if you are using some flavour of .net you will probably use Microsofts hashing of it.
For inline comments I prefer to comment blocks of code: This is what the next block of code does (or should do). Do not comment a single line as that is pointless and often less than helpful. Exceptions to this is when a workaround is performed when the language implementation has a bug - this is useful when working with VC6.
As others have said, code should be self commenting, so names, events, objects should all reflect and read as easily as possible to what they're trying to achieve.
Apart from that additional comments should be used when something needs further explaining, as to why you went down a way (this formula, and values were chosen because of x, refer to bug, etc).
(If this is .NET and you are also wanting to provide a windows helpfile you could also look at Ghostdoc and the commenting it provides, and Sandcastle [a Windows helpfile builder that will take code xml comments and build a helpfile from your API].)
But generally the rule of thumb is that 99% of the time the code should be readable, logical and broken down into methods that make sense so that you don't really need anything apart from the code, and then comments are only to fill in the blanks on what really needs explaining further.
I push for function-header comments, but only ask for intra-function comments when they're absolutely necessary to describe, say, a work-around for an API bug or some other essential but non-obvious technique.
Header comments should:
Other comments, notes, or usage examples can be included as well, but are not required.
And yes, comments can and do become inaccurate. There's no escaping this, but there's no reason to throw the baby out with the bathwater either. When correct, comments can save you a lot of time digging through code trying to suss out its purpose. Trust the comments, but verify - and take a minute to correct inaccuracies when you encounter them.
First and foremost, comments should be clear, concise, relevant to the code they are commenting, and provide value that isn't readily available by actually reading the code. For example, documenting why a particular hashing algorithm was chosen over the others available for a password hash function.
If you are using one of the .NET based languages, you should use XML comments for both public and private members as Visual Studio will use this information to display intellisense for your classes. You can also use these comments to automatically generate API documentation using tools like SandCastle. This does mean the information needs to be kept up to date, but that should be a very small percentage of time spent. If you aren't using one the .NET based languages, there are other tools (like Doxygen or Javadoc) that provide comments and functionality similar to XML comments.
You should also be consistent in what you document and how you document. If you put a file header, put the same header in each file (changing only what is necessary, such as the file name).
I usually just use these pointers.
I use "header comments" to document functions, classes etc. Usually this is more for documentation than comment. I use C# and Visual Studio and you get some nice features when you use XML comments for this.
Comments should tell why you did something and not what you did. Your code should be clear enough to show that, if it's not then change the code. Comments repeating what the code does are as bad as duplicate code. When the code is updated the comments are sometimes forgotten causing more harm than good.
Comments should be kept to a minimum. Comments are loc's to and need to be maintained. So do without them if you can
Self-commenting code is a bit of a falicy in my opinion. There's no such thing. Sure, code needs to be clear and concise, but that's not about comments. That's about code quality.
Comments, on the other hand, should explain what problem the code solves and why. The way the code works is understood by reading the code itself; the comments should be about why the code is there at all.
Simply put, comment on the why, not the how. I realize that this is redundant given the other answers, but it cannot be stated enough.
Write your code and comments so that it will be easy to read when you have to come back in 6 months and fix the bugs that will be there. Also, if the code is written such that the logic and intent are clear, beware of over-commenting. This can make the code hard to read. In other words, be nice to the person that has to maintain the code.
I highly recommend reading Code Complete and the section on commenting there.
I picked up a commenting convention from another developer when I was at university that has served me very well over the years. Its idea is to enable you to scan through a file as quickly and easily as possible, either looking for something or to get an overview of its structure. I prefix every public or protected method or property with the following comment structure:
/* ====== MethodName ====== */
/// <summary>
/// XML comments go here
/// </summary>
void MethodName()
Of all the conventions I've seen so far, this one, to my eyes at least, seems to be the clearest way of making each method stand out, and it makes it easiest to scan quickly through a file of source code. Having said that, I hate XML comments with a vengeance because of the visual clutter of the angle bracket tax, and I wish that Microsoft had settled for something more along the lines of Javadoc or PHPdoc:
/* ====== methodName ====== */
/**
* Doc comments go here
*
* @param A parameter
* @returns A number
*/
int methodName(String param)
Beyond that I try to make the code as self-documenting as possible. Every method should ideally perform one specific task (which may of course be broken up into sub-tasks), and its name should describe what it does.
I do believe this article is relevant. http://www.codinghorror.com/blog/archives/001150.html
What about comments for the sake of people needing to skim the code later to find out where it broke or what may need to be updated. Here is an example I found from the web.
http://www.example-code.com/csharp/ssl_async_client.asp
I think this example is pretty good if you are wanting to debug this code. maybe more "Why I am doing it this way" is needed but not bad.
I find that much of what I am doing is debugging and maintaining apps that are completely different in there codebase written by people that are long gone or not available. To find a bug otherwise you may have to read every line of code, seems inefficient no?
I would like to see more examples of good commenting examples that people have.