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.
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
Use Proper Casing for Members
|Interface||Pascal with I prefix||IStrategy|
|Enumeration Representing Bit Field||Pascal in plural||SearchOptions|
|Private Field||Camel with underscore||_scheduler|
|Protected Field||Camel with underscore||_scheduler|
|Readonly Field||Camel with underscore||_listItems|
|Static Readonly Field||Pascal||ListValues|
|Type Parameter||Pascal with T prefix||TValue|
|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.
- Other stuff
Than follow access modifier.
After access modifier follow the type of the member.
The least significant sorting attribute is a declaration modifier.
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
- 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
Don’t Repeat Name of Class or Enum in Members
ColorEnum are simply not acceptable.
Name Methods Using Verb-Object Pair
Use verb naming only when it is descriptive enough.
Namespace should be named according this pattern:
Assembly name should match namespace definition and files should be placed in proper folders inside the assembly.
Suffix Attribute Class with “Attribute”
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.
- 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”.
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.
Class containing tests for tested class should be named after this class with “Test” suffix.
Unit test methods should follow this naming scheme:
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.