Let's get cosmetic on C# documentation

I am gathering here just a few C# documentation cosmetic tips that I apply in my own projects. I do not pretend to have achieved any absolute truth or any optimal practice with those tips. I just find them convenient when applied with consistency.

• #region #endregion directives can be great, but caution not to overuse them by putting a dozen of directives within a 200-lines long code file. Indeed, if region makes the code structure more apparent, region also makes the code less proofreadable because you have to open the regions to actually start reading. As a rule of thumb, region directives should only be used for at least 100 lines.

• XML documentation is great too. But again, Visual Studio makes it quite easy to overuse XML documentation. Basically, with 3 strokes you can generate up to a dozen of lines of empty comments. Yet, if those comments are not completed with insightful content then you’re just polluting your code. Here, I define insightful as being any comment that goes beyond the information implicitly provided by the method signature itself. Example: if you have a method named Foo.DeleteUser(Guid userId) do not tell me, that userId is the user identifier. I know it because it’s obvious. Tell me what happen when no such user exists. Documentation has to be maintained like the rest of the source code. Useless documentation only makes the code harder to maintain.

• In the case of the internal project, wrapper methods (methods that basically forward the call to another method) is the kind of objects where it’s actually better not to document. Instead, I prefer using a <seealso/> XML documentation reference. Indeed, documenting a wrapper is pretty much like duplicating your documentation. If this documentation is exposed to your customers, then you do not have much choice, you have to duplicate the docs (MSDN are full of replicates), but for the internal development needs, I found such replication far from being cost-effective. Thus I avoid the docs replication through XML references.