C# Coding Conventions and standards

    Having your team follow the same coding conventions and standards can help make your software more readable and more uniform by keeping things consistent and clean.  This facilitates maintainability by allowing members of your team to be able to read and comprehend code written by co-workers more quickly without having to mentally run a background filter to interpret layout and style differences, etc.  It also fosters best practices and can contribute to keeping your APIs consistent as well.  That said, the stringent expectation of adherence to coding conventions has to be balanced against other factors.  There is no need to become a Nazi about this, but it certainly helps if all members of the team strive to be consistent with one another.

    One way to develop a good feel for solid coding conventions is to read software written by experienced and talented software developers.  As Bill Gates once said “The best way to prepare is to write programs, and to study great programs that other people have written”.  Hopefully you will get more out of such an endeavor than simply learning good coding convention habits, but that is certainly an important piece of the puzzle if you want to write good software.

    If time permits a team or organization would do well to create some sort of formalized coding convention specification that outlines good suggestions for formatting and style.  I am currently putting one together and it occurred to me what better place to go to then to the source itself, Microsoft.  In so doing I found the following “Internal Coding Guidelines” on the MSDN blog of Microsoft coder Brad Adams.

Brad Adams - Microsoft C# Internal Coding Guidelines

    I found that most of the recommendations concerning spacing, single line statements, commenting, bracing, tabs and indenting, etc. seem to be pretty universal among C# developers.  Don’t forget that the Visual Studio IDE has a “Format Document” command in the edit menu that will handle most of those types of conventions for you, and can be useful in the event that anything gets out of sync as you are authoring your code.  One section particularly worthy of discussion, however, was the “naming” guidelines.

An excerpt…

Follow all .NET Framework Design Guidelines for both internal and external members. Highlights of these include: Do not use Hungarian notation Do not use a prefix for member variables (_, m_, s_, etc.). If you want to distinguish between local and member variables you should use “this.” in C# and “Me.” in VB.NET. Do use camelCasing for member variables Do use camelCasing for parameters Do use camelCasing for local variables Do use PascalCasing for function, property, event, and class names Do prefix interfaces names with “I” Do not prefix enums, classes, or delegates with any letter The reasons to extend the public rules (no Hungarian, no prefix for member variables, etc.) is to produce a consistent source code appearance. In addition a goal is to have clean readable source. Code legibility should be a primary goal.

    After reviewing this list I realized that there are a few practices in my own conventions that I may or may not need to revisit. 

    As a habit probably picked up from years of coding against the .NET Framework I already employ Camel Casing for member variables, parameters, and local variables, while using Pascal Casing for function, property, event, and type names.  Recall that camel casing is the practice of using lower case for the first word in an identifier and using upper case for the first letter of each proceeding word (i.e. camelCasing).  Pascal Casing is using uppercase for the first letter of each word in an identifier to include the first word (i.e. PascalCasing).  One side effect of sticking to conventions is that it is easy to keep track of what type of identifier you are looking at when reading code.  For example, I can always rely on the fact that properties utilize Pascal Casing while local variables do not, which saves me from having to scan back and find the definition of an identifier when reading code.

    There are a few conventions here that I myself am guilty of violating, but I’m not entirely sure that it is necessarily a bad thing assuming that you are consistent.  For example, I don’t like the recommendation to not prefix fields / member variables with an underscore in order to differentiate them from local variables in methods.  This document recommends that instead you always use the “this” keyword to identify fields.  This does not differentiate between properties and member fields.  I also can envision scenarios where a method’s readability might suffer when littered with “this” prefixes.  This document is a bit dated and was established before C# allowed for automatic properties.  Before automatic properties field variables were probably referenced much more frequently throughout a class definition due to the fact that private members are less likely to require accessor and mutator logic and wrapping up all fields in properties would have resulted in a lot of extra typing in order to define the backing field variables, and then also the property definitions from which to access them through.  The payoff was maybe not worth the effort because there would rarely if ever be any logic in the get and set blocks of the property definitions.  With automatic properties this is no longer an issue.  My preference is to wrap my private fields with properties even if the properties themselves are not public or protected and require no accessor or mutator logic, and if it is required, I prefix the corresponding backing field with an underscore and use camel casing.  The underscore is handy and prevents you from mistakenly directly accessing field members instead of properties.  It also allows me to differentiate between local variables and field members because local variables use camel casing, properties use Pascal Casing regardless of their scope, and field variables utilize camel casing but are prefixed with an underscore.  Regardless, the only place field members are normally referenced in my code is within the accessors and mutators of property definitions anyway, so in my opinion, the underscores do not become an issue for readability.

    The other item that I take issue with is the admonishment not to utilize Hungarian notation.  Hungarian notation is an identifier naming convention where the identifier is prefixed with something that indicates the type that the identifier references.  For example, intCount or strName.  I am generally relieved to see an exodus from the dogma of Hungarian notation and in most cases I do believe that it was grossly overused, particularly with narrowly scoped local variables whose declarations were already staring you in the face and whose type was already glaringly obvious.  However, I do think that some types of API’s can be more cleanly leveraged when their types are referenced with Hungarian notation, such as GUI APIs.  To this day I always prefix my textboxes with txt and my comboboxes with cmbo.  I think it enhances readability.

    The other thing I don’t see mentioned is using uppercase in conjunction with underscores for constants.  As far as my public APIs go, I do not normally use this convention for enumerations, constants, or readonly fields, however, I do still find it useful to often identify my private constants in this manner, as in “THIS_FIELD_IS_FIXED”. 

    I don’t believe that there is only one “right way” to institute coding conventions and standards.  I do think that the consistency and uniformity of doing so can keep your APIs clean and keep your team’s code consistent for readability.  My recommendation is that you get together with your team and try to establish a baseline of convention suggestions that you can all agree upon.

 

A couple of other useful related resources I found that were also available on MSDN:

.NET Framework Guidelines for Names

http://msdn.microsoft.com/en-us/library/ms229002.aspx

 

Design Guidelines for Developing Class Libraries

http://msdn.microsoft.com/en-us/library/ms229042.aspx

 

I would recommend that you look those documents over and bookmark them.

Comments

[Russ]

I am learning from this. Keep this going John.

[John]

Thanks Russ! I am going to start incorporating some less technical-focused and more general / career focused material...partially due to the fact that I want to make the blog useful for aspiring developers as well as professional ones, and partially because I don't want to exclude developers whose primary tools do not include C#. I really appreciate the fact that your checking out the blog, glad to at least have one reader lol. Either way, I'm having fun with it and benefitting from examining and reviewing the material for my posts...I'd like to have you as a guest contributor if you ever have any articles you'd like to contribute.

[Michael]

Just want to point out - there are two main types of Hungarian notation: Systems and Apps. Systems Hungarian prefixes variables with their types, which is rarely necessary. Apps Hungarian prefixes with the variable usage as you describe. "Don't use Hungarian" is a knee-jerk reaction to feeling the need to prefix everything. I think you have the right of it here.

[John Connelly]

Thank you Michael