Having just read Pattern Orientated Software Architecture Volume 1: A system of Patterns then there is a great comment in the section where they talk about Idioms and in-house coding standards. The biggest thing I note is that what is always missing is the justification? Why should you use Pascal Case? Why prefix with hungarian?
The most worrying thing that comes from this question is whether this is missed from standards because the author(s) could not justify their decisions but it felt right. In that vein I can actually think of several Anti-Standards, where I can't justify the case but I can dismiss the alternatives. For example I can easily argue against Hungarian notation, as it drops developer performance in a modern IDE because it impacts auto-completion (see IDE Features below). So how do I justify these without just saying it is the standard that everyone else uses.
Coding Standards
IDE features
Modern IDE's are fantastic tools that provide many times more information than a simple text editor. With features such as syntax colouring, tooltips and pre-compilation, they are able to tell you precisely what type of object you are focused on (hovered with a mouse, or cursored to). This negates a lot of the arguments for the need to explicitly state the type of the object in its name (e.g. Hungarian notation).
Then we come to auto completion, which works from left to right and takes all the characters you have typed in the word so far and can automatically extend them to a full variable name or type. Well if you aren't sure of the type (you may have subclassed) then the completion wont work due to the incorrect prefix. If you haven't already found it, then ctrl-space is about to become your new best friend in Visual Studio.
Basic Principals
This section discusses the building blocks and patterns that are later used to define a working set of rules.
Prefixing
Prefixing is a way of reducing the effectiveness of autocompletion in your IDE.
How often have you looked in a database and seen that every stored proc is prefixed with p_addUser, or that every table is prefixed with the domain it works in (except the database only works on the single domain) e.g. wl_Users? My personal feeling is that these days the prefix is removing a huge performance boost to our daily work. Without the prefix we can press c, and have the IDE help us to find customers or type man to skip over mail and land on manuals. Can't you show these domains via a NameSpace?
All variables,properties, methods, enumerations and constants should be named so that their scope is apparent, i.e.
Capitalisation Styles
Style name | Notes | Example |
Pascal case, TitleCase | You can use Pascal case for identifiers of three or move characters | BackColor |
Camel case | The first letter of an identifier is lowercase and the first letter of each subsequent word is capitalised. | backColor |
Uppercase | All letters in the identifier are capitalised. Use this convention only for identifiers that consist of two or fewer letters. | System.IO |
Hungarian Notation | The description is prefixed by its type. See notes on Prefixing above | StrColorName, datToday |
Standards
This section defines the actual Standards that are in use.
Code Structure
All variables,properties, methods, enumerations and constants should be named so that their scope is apparent, i.e.
Scope | Types | Standard | Justification |
Global | Anything available throughout the entire application. Includes Namespaces, class definitions and enumerated types defined in a Namespace namespace MyCompany.Bank.Example
{
enum Issuer
{
Government,
Corporate
}
public class Bond | TitleCase, UpperCase for short names | Follows standard as used by Microsoft for System libraries |
Class Public | Anything that a class exposes to the rest of its namespace, or another namespace that is using the namespace. Includes the enumerations, properties and methods public class Bond
{
enum Issuer
{
Government,
Corporate
}
public override string ToString()
{ | TitleCase | Follows standard as used by Microsoft for System libraries |
Class private | Anything defined that is available within the class. Usually just private or protected member variables. public class Bond
{
private int _entityId; | _camelCase (CamelCase preceeded with underscore) | Informs developer that they are using an internal field when they may be a publicly available property or method that’s ensures data integrity. |
Method private | Objects that will go out of scope and the end of the method or property, includes local variables and parameters public double Years(DateTime marketDate)
{
StringBuilder result = new StringBuilder(); | camelCase | Informs developer that they are working inside the method only. Care may be required to dispose of objects, or alternatively the developer may be free to do what they want with object as it is short lived. |