This is a red herring argument I hear often from developers that don’t like maintaining comments in code. By asserting that too many comments will detract from the quality of the code, it’s easier to get away with fewer or none at all. (see Slippery Slope)
I’ve yet to see code that is commented to such excess that it’s obtrusive, cluttered or unmanageable. Many examples of excessive commenting exist in sample projects or educational applications. In these cases the comments usually serve as supplement (or replacement) to the instructional text. I see this often on The Code Project in which the author is showing examples in context.
Example from http://www.codeproject.com/Articles/555923/ASP-NET-WebAPI-Hosting-Techniques
In the real world, rarely have I found a developer willing to write full paragraph in comments. It just doesn’t happen. But let’s set that aside for now. Even if we were to write an entire essay to document comments, there are very simple ways to make them virtually disappear:
1. Collapse XML Documentation Comments
If you’re taking advantage of the built in XML Documentation Comments, Visual Studio will handle these like XML and allow you to collapse at the parent node. This works for all XML based documentation comments and collapses the comment to a single line.
A single line for comments is far from what any reasonable person might consider as “clutter”.
Wrap Large Comment Blocks in Regions
It’s inadvisable to write massive segments of comments within a code block. The changes of others reading a dissertation while trying to efficiently manioulate your code are slim. If you must add a Outlining regions can be useful for hiding excessive comments as well as hiding sensitive code. You’ll find as much dispute over the use of regions as commenting code, but there’s a useful purpose. Most of the complaints around regions stem from the coder not knowing the shortcuts to expand and collapse outlining.
To alleviate confusion, it’s important to name your region appropriately. A useful name on a region will notify coders that the collapsed area contains only comments and is not necessary to expand.
Again, I don’t know too many reasonable developers that deem a single line of collapsed text as obtrusive.
Helpful Shortcuts
For those of you that hate the comments and have developers that follow the above conventions, you’re in luck. The following commands will speed things along.
In VS 2005+:
Ctrl + M, Ctrl + P will expand all outlining (Regions, Comments, Methods)
Ctrl + M, Ctrl + O will collapse all outlining (Regions, Comments, etc.)
For those of you who shy away from key commands, the same options are available via the Edit > Outlining menu
”
Wrap Up
These are a few dead simple methods of concealing comments as well as exposing them when needed. Wrapping comments in outline blocks (XML and Regions) leaves future coders with comments they can read and review if needed, or leave collapsed if they wish to ignore. If these conventions are followed, no amount of commenting inside the outline will cause any more clutter than a single line.
As a rule it’s best to keep comments succinct and contextual. Short, well placed, useful comments cost nothing to add and have the potential to save hours of confusion in the future.