Are there standard formats for comments within code? [closed]

Question

I'm wondering if people have a standard format for comments in their code. Not things like xml comments for a method or class but rather comments within a method.

---

See also:

Is there a standard (like phpdoc or python’s docstring) for commenting C# code?

Answer 1

You should really consider a couple things to make good comments beyond formatting.

1. Do not simply restate what the code is doing. For example,

 // Start the services
 StartServices();

is a frigging terrible comment!

2. Describe why. Why is the code doing what it's doing? What's the business assumption or algorithm step?

3. Format your comments for maximum readability. Tab them properly, leave spaces where necessary, etc.

4. If someone has already started commenting in a standard way, don't break that standard.

5. Check this article on MSDN about writing effective comments: http://msdn.microsoft.com/en-us/library/aa164797.aspx

Answer 2

// I usually write comments like this

Where I work it is required to use standard xml comment style for most of the declarations (classes, methods, some properties) (we use C#).

Sometimes you can see header/footer comments in use.

/****************************************************/
// Filename: Customer.cpp
// Created: John Doe
// Change history:
// 18.12.2008 / John Doe
// 14.01.2009 / Sara Smith
/****************************************************/

/* Here goes a lot of stuff */

/****************************************************/
// EOF: Customer.cpp
/****************************************************/

Something like this was used at one of my old places of work. In my opinion too much of unnecessary stuff. Change history is nicely seen these days through a version control system.

In many good software shops there are internal guidelines as to when and how to write comments. Documents are typically referred to as "Source code style policy" or something. It is very important to adhere to one common style in commenting the code.

Of course this commenting hype shouldn't go too far as to comment every little piece of code, especially the obvious ones.

/// <summary>
///     Handles the standard PageLoad event
/// </summary>
/// <param name="sender">
///    Event sender
/// </param>
/// <param name="e">
///    Event arguments
/// </param>
public void Page_Load (object sender, EventArgs e)
{
    // Do something here
}

This one is a good example of over-obsession with commenting. Something like this adds exactly zero information but only adds noise to the source file. And we have to do it at work as required.

My personal opinion is add comments when you have something to say or explain, not just for the sake of commenting everything.