Search code examples
comments

Are there standard formats for comments within code?

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?

Solution

  • 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!

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

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

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

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