commenting code C# visual studio best practice

Question

I'm looking for a rather arbitrary answer, so this might more be a discussion. I'm wondering what the best practise for commenting my C# code in visual studio is. Right now I'm using the triple /// to generate the xml and use sand castle to build a chm or html file. But my problem is that I use code comments for two reasons:

1. When other developers are using my code they can read the documentation, both intellisence and the chm. or html file.
2. But I also use commenting as reminders to myself. So I can remember my thoughts when I come back half a year later, to some complex methods.

How can both goals be accomplished without interfering with each other, and in the same time be a quick task, not taking a lot of coding time?

Answer 1

The best advice I can give you is:

Don't comment bad code; rewrite it!

If methods are very complex, most of the time you are doing something wrong (not always, but very close to always). Writing readable code is hard, but it pays of, because writing good comments that you (or your colleges) will understand a year later is hard as well (and perhaps even harder). Ways to make things clear is by breaking methods up in smaller well named methods and using very clear variable names.

A book that has helped me a lot in creating better code was Robert Martins Clean Code. If you haven't read it, please do. And let all the developers in your company read it.

Good luck.

Answer 2

Use /// comments to document your public and protected API. Use <remarks> to describe how your API should be used. The audience of these comments are other developers using your code.

Use // comments to comment your code whenever the code alone isn't adequate to fully understand what is going on. The audience of these comments are yourself perhaps three months out in the future or another developer going to maintain your code. You can use special comments like TODO or BUGBUG to flag codes you have to revisit.