What do you think is the best C# Commenting Structure? Specifically with Visual Studio.

Question

Over the years as I have gone through school and been working in the industry I have often asked people for advice on commenting. Sadly, as we all know, commenting with many developers is something that is taken as a side note and not much else. With that said I usually get a fairly general answer. Really this does not help much to see what will really help as time goes on.

So, what do you think is the best way to structure C#, with Visual Studio, commenting?

Answer 1

"Plenty and often" --Bilbo, The Hobbit.

More seriously, comment things that are not obvious, and tell the reader what the goal of the code is, and perhaps why you chose it.

That's not going to change based on language.

Answer 2

At the very least, I would comment all parts of your public API, using a triple-slash XML comment block. This will make it easy to auto-generate documentation if and when the time comes.

Beyond that, I would comment any particular algorithms or pieces of code which are going to be hard to decipher in six months time. This 'selfish' approach to commenting (i.e. assume you'll have to maintain this code later) often leads to the best balance of ample documentation without overkill.

Answer 3

I try to follow some basic guidelines when writing comments.

• Comments should be simple
• Comments should provide clarity
• Write documentation before you write implementation
• Document why you're doing something, not what you're doing.
• Use built-in (XML-style) comments for interfaces, methods, properties, and classes.
• Provide a summary at the top of every file (e.g., Something.cs) with the file name, description, development history, and copyright information
• Add comments for bug fixes (with bug number, if appropriate)
• Make use of helpful annotations like //TODO //BUG and //BUGFIX
• Don't comment out code unless you plan to use it
• Add comments above the line(s) of code they apply to, not to the end of the line
• Try to limit comments to a single line
• Use // instead of /* */ for multi-line comments
• Be clear--do not use "foo," "bar," etc.
• Follow casing rules where appropriate (i.e., camelCasing and PascalCasing)

Answer 4

Personally I use a combination of triple slash, SandCastle XML comments and inline comments for more complicated sections. Comment often but keep it concise, nobody needs to read reams of fluff before then can figure out what something does :-)