.Net Coding Standards

The C#/.Net coding style that I recommend is documented in MSDN:

MSDN’s “Design Guidelines for Developing Class Libraries”:

MSDN’s “Guidelines for Names”:

For more in-depth guidance, I consult Microsoft’s authoritative book, Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries. Although it’s a bit pricey, it also includes a DVD with several video presentations.

The following tools are recommended to help developers write code that falls within the above guidelines:

StyleCop: Analyzes C# source code to enforce a set of style and consistency rules. Integrates with Visual Studio Premium and higher. Also runs as a stand-alone. Originally developed by Microsoft. You may not want all the rules turned on, so you may want to maintain a custom “Settings.StyleCop” file for your project.

FxCop: Static Code Analysis (beyond just naming and syle).

ReSharper (R#): Intgerates with StyleCop. If StyleCop is not installed, uses its own rules (a practical subset of StyleCop). If all developers on a project have license for ReSharper, I would suggest starting with just ReSharper rather than StyleCop. If not, then ask them to install StyleCop and maintain a “Settings.StyleCop” file for your project.

this. vs _ (underscore)
By default StyleCop wants you to reference member variables with “this.”; however, many prefer to use the underscore (“_”) prefix naming conventions for private member variables. It is also familiar with many C/C++ developers. I recommend “_” over “this.” due to its brevity and readability.

var is a C# keyword for compiler-inferred early binding. Aside from normal LINQ use, it is also preferable to use it when the type is explicitly stated on the right-hand side of the assignment (when obvious to the reader without use of IntelliSense), such as in the case of an explicit new or a Generic (“template”) factory method decorated with the type (Generic collections/containers, service locators, etc.)

Spaces rather than Tabs
For C# (and SQL) source code, use spaces rather than tab (Visual Studio: Tools, Options… set tab and indent size to insert 4 spaces rather than “Keep tabs”)

Refactoring and Minor Fixes
When modifying legacy code that deviates from the naming/coding standards, use common sense:
• If making limited bug fixes, it’s ok to stick with the existing (legacy or non-standard) naming conventions so that your changes are easier to see in version control history. But if your refactor involves breaking this out to new classes (or even new methods), then it’s preferable to use the correct style/convention.
• If there is a need to make global changes to names and/or whitespace, check in those changes separately whenever possible, rather than mixing functional changes in at the same time.
• Likewise, incrementally check-in (and test) refactored code in separate step (separate check-in) from new functionality. If something goes wrong later it’ll be easier to see in version control history.
• If your new changes in an area of code are larger than remaining legacy code, then consider upgrading the legacy code (but as separate check-ins where possible).
• A refactoring tool may help.
• Remove dead code if possible.
• Avoid duplication.
• Most important: please don’t break tested code just to make it look better.

History Notes
Although it’s ok to include bug tracking or requirements tracking Ids in code comments, keep in mind that comments in version control check-ins are also for that (don’t make you code unnecessarily difficult to read). Also avoid maintaining version history lists/headers directly in source files: that’s also what version control comments are for.

Region Abuse
If your class has a lot of regions (especially those that can be classified under a certain category or related functionality), then consider refactoring: break them up into smaller classes. Avoid using regions within a method just to decorate bug or requirements tracking Ids at the expense of readability.

Compiler Warnings
Your code should compile without warnings if possible. If you must suppress warnings with a #pragma directive, you must have a good reason (either a well-known issue or something documented in comments).

Avoid bad code, and fix the problem rather than contributing to it
Please don’t write obviously bad code (easy examples: goto’s, gigantic switch statements, large “arrow anti-pattern” else-if blocks, God classes). Apply refactoring techniques when it makes sense. If you have to modify code that already looks like this, then consider if a refactor is within scope of your delivery or release (and don’t let it sit forever in your backlog).

DO occasionally run the STA code metrics preinstalled with VS2010 Premium/Ultimate to analyze the Maintainability Index (MI), Cyclomatic Code Complexity (CCC), Class Coupling (CC), and Depth of Inheritance (DOI) of your code.

With all this in mind, please don’t break tested code just to make it look better.

Leave a Comment