C# Naming and Layout Guidelines

Naming and layout guidelines are sets of rules that defines how you should name things and how you should organize and structure a code in your code base.

When you are working alone on a project you could act like a cowboy and name things after whatever you want. But as soon as some other person is involved you should consider to discussing how the things will be done. The person can (and eventually will) be you in the future when you need to make some changes in the project and if you were doing things in the cowboy style you are going to hate yourself. How would you feel if you have to maintain a project after such cowboy?

There are only two hard things in Computer Science: cache invalidation and naming things.
Tim Bray

As the team grows larger these rules becomes even more important. Uniform standards produces much more readable, understandable and maintainable code and the productivity is what we should all aim for, right?

I applied the guidelines below in several companies I have been working for and they works great. You can modify them for your needs. They should serve as a recommendation how it could be implemented. The great thing is that some of them can be applied automatically with proper tools. Visual Studio can define how the code is going to be formatted and Resharper is able to do more advanced stuff with your code. You can define templates and settings with your rules and distribute them to your team members. Global guideline settings and automatic cleanup in your team just for the price of creating one. Nice!

Enough talk! Let’s take a look at those guidelines.

Use Proper English

Favor readability over brevity. For example CanScrollHorizontally is better than ScrollableX.

Use Proper Casing for Members

Identifier Casing Example
Class, Struct Pascal StrategyManager
Interface Pascal with I prefix IStrategy
Enumeration Pascal LoggingLevel
Enumeration Value Pascal Info
Enumeration Representing Bit Field Pascal in plural SearchOptions
Event Pascal Click
Private Field Camel with underscore _scheduler
Protected Field Camel with underscore _scheduler
Constant Field Pascal Pi
Constant Variable Camel definitionKey
Readonly Field Camel with underscore _listItems
Static Readonly Field Pascal ListValues
Variable Camel value
Method Pascal ComputeValue
Property Pascal Value
Parameter Camel parameter
Type Parameter Pascal with T prefix TValue
Namespace Pascal System.Drawing
Abbreviation with 2 and less letters All Caps UI, IO
Abbreviation with 3 and more letters Pascal Xml, Http

Use Proper Class Layout

Use the following order to position all your members inside the class. The resulting layout is the combination of all the lists provided with descending priority. That means that on the top of the file there will be all public const fields followed by internal const fields.

  1. Fields
  2. Delegates
  3. Events
  4. Properties
  5. Indexers
  6. Constructors
  7. Finalizers
  8. Methods
  9. Other stuff

Than follow access modifier.

  1. public
  2. internal
  3. protected
  4. private

After access modifier follow the type of the member.

  1. const
  2. static
  3. readonly
  4. nothing

The least significant sorting attribute is a declaration modifier.

  1. virtual
  2. abstract
  3. override
  4. new

Use Abbreviations Wisely

Use abbreviation only for well-known terms such as UI, XML …

Don’t Use Hungarian Notation

Do not add prefixes for adding metadata to variable name. Exceptions are private fields with underscore prefix and UI elements where the prefixes are acceptable.

Name Identifiers According Its Meaning

  • Do not name identifiers according to their type. GetLength() is better than GetInt().
  • Don’t use short names and names that can be mistaken with something else.
  • Consider naming Boolean values with the Is, Has, Can, Allows, Supports … suffixes.

Name Types Using Nouns, Noun Phrases or Adjective Phrases

Good example is BusinessBinder, SmartTextBox …

Don’t Repeat Name of Class or Enum in Members

Names like ColorEnum are simply not acceptable.

Name Methods Using Verb-Object Pair

Use verb naming only when it is descriptive enough.

Namespace Naming

Namespace should be named according this pattern: Company.Product.Feature.Subnamespace.

Assembly name should match namespace definition and files should be placed in proper folders inside the assembly.

Suffix Attribute Class with “Attribute”

For example BasicAuthorizationAttribute.

Suffix Exception with “Exception”

You shouldn’t create custom exceptions too often. It is desirable to use built-in .NET framework exception. But if you really need create your custom exception, use this suffix.

File Guidelines

  • Name Source File According Containing Class
  • Place Only One Class, Struct, Enum or Interface to One File

Event and EventHandler Naming

  • You should use verb or verb-phrase to name events (Click, Deleted, Closing)
  • Suffixes –ing and –ed are used for expressing pre and post events.
  • Delegates related to events should be named with the “EventHandler” suffix.
  • Delegates related to callbacks should be named with the “Callback” suffix.
  • Prefix methods registered to events with “On”.

Extension Class

Class that contains extensions should be named with the Extensions suffix.

Do Not Use Inline Comments

Use comments only to describe really hard parts of algorithms or decisions. Other code should be self-descriptive.

Use // for Comments Instead of /**/

Do not leave commented code inside the class. This is your source control systems job to keep code history.

Comment All Public Members with XML Comments

Use proper C# MSDN style comments for all exposed public members inside your assembly.

Do Not Use Regions

Use regions as less as possible. For example hiding implementation of an interface unrelated to the class functionality is acceptable.

Unit Tests

Class containing tests for tested class should be named after this class with “Test” suffix.
Unit test methods should follow this naming scheme: TestedClassName_TestedMethodName_ExpectedOutcomeOrCondition().

Conclusion

Remember that these guidelines should be the result of the team discussion and mutual agreement. You can modify them but if you apply at least some of them your productivity is going to increase and your code is going to contain much less bugs and errors. So keep in mind that naming standards a layout guidelines are very important.


Did you like the article? Send me a comment!