Professionalism, Craftsmanship, Discipline
My naming standards for C# code are based on Microsoft’s naming guidelines, found here.
It’s difficult to name things in your code well. But I’ve lost count of the number of times misunderstandings due to poor naming have caused expensive mistakes. So, naming things well is important.
For any given piece of functionality I typically I start by writing a test and then just write the code I need to pass the test without too much attention to style – it just has to pass the test. I try and work one principal method at a time and at this point it probably does more than one thing & I start refactoring it out into separate methods and probably one or more new classes, re-running the tests as I go. All these new methods, fields, classes need names.
I try and name things well when I create them but I’ll probably rename them, often more than once. The last thing I do before finishing up is to re-check all the names and make sure I’m happy with them. I frequently run names past colleagues and sometimes resort to using a thesaurus.
I’ve based my naming standards on Microsoft’s own best practices document, which can be found here. It includes a requirement to use CLR names rather than language specific names where the only semantic meaning is the type e.g. ToInt16(…) rather than ToShort(…). I thought it would be useful to reproduce Microsoft’s table of CLR names and their language aliases below…
CLR Type Names
| C# | Visual Basic | C++ | CLR |
|---|---|---|---|
| sbyte | SByte | char | SByte |
| byte | Byte | unsigned char | Byte |
| short | Short | short | Int16 |
| ushort | UInt16 | unsigned short | UInt16 |
| int | Integer | int | Int32 |
| uint | UInt32 | unsigned int | UInt32 |
| long | Long | __int64 | Int64 |
| ulong | UInt64 | unsigned __int64 | UInt64 |
| float | Single | float | Single |
| double | Double | double | Double |
| bool | Boolean | bool | Boolean |
| char | Char | wchar_t | Char |
| string | String | String | String |
| object | Object | Object | Object |
With all of this in mind, here are the guidelines I use for my own code…
1: Don’t use names that are difficult to articulate. You’ll be discussing code with your colleagues a lot, so it really helps if the things in are easy to say out loud. If I can’t pronounce it, I don’t use it.
2: Avoid acronyms that aren’t in common use, either generally or inside your solution domain. Acronyms should be pronounceable (see rule 1).
3: Names should express the purpose of the thing they name.
- Classes, properties & fields are nouns because they are substantive.
- Methods are verbs because they do something.
- Use solution domain names wherever you can.
- The smaller the scope the less I worry – for (x=0: x++, < upperLimit) is fine.
- The bigger the Scope the more I worry – X is a bad name of an API method
- Names should add context if it’s not gratuitous. “CarId” doesn’t add much information in a “Car” class. “Id” is probably fine.
4: Avoid encodings like Hungarian Notation, the IDE takes care of this info for you.
5: Interfaces start with an “I”, it’s a C# thing.
6: Form
- Classes, Properties, Methods, Types are PascalCase.
- Fields in class scope are camelCase and start with an underscore*.
- Fields in methods are camelCase without the underscore.
- Parameters are camelCase without the underscore.
* I hate this because it’s really an encoding. But it is useful and it’s Microsoft best practice**. You can’t argue with the Man.
** Microsoft best practice evolves, so this may change. However, always stay with a consistent style inside any single project and solution. Don’t break the project bit of this and only break the solution bit after very serious consideration, and then don’t do it.
These are my guidelines for my own code. There are some caveats …
When working in a team adopt the team’s style because consistency is important. It’s fine to contribute to the discussions but the team rules. If you’re in a lead role then your influence on this discussion should be significant but you must carry the whole team with you.