Reddick .NET Conventions

These are a set of notes toward a set of .NET conventions. They are not ready for prime time, but keep checking back.

Version 0.90

Copyright © 2002-2003 by Gregory Reddick

Index:
Introduction
Summary

Introduction

• More readable: Conventions allow a reader to understand the meaning of the code with less effort.
• More maintainable: The code can be more reliably changed to fix bugs and enhance functionality.
• More reliable: The code is more likely to perform as expected.
• More efficient: The code performs faster or consumes fewer resources.
• More consistent. Programmers can more easily read each other's code.

These conventions come from several sources. One source is the Reddick VBA Naming and Coding Conventions, that have been in use since 1992. Others come from the standards that Microsoft has put into place in the .NET Framework. Microsoft has implemented two tools that help with verifying that conventions have been met: FXCop and StyleCop. In a few places these conventions are slightly different than the rules that these tools implement, but in most places they concur. Xoc Software will also release a StyleCop library. Where possible, the FXCop or StyleCop rule that enforces the convention will be listed.

The current version of these conventions can always be found on the Xoc Software web site: http://www.xoc.net.

Casing

There are several different forms of casing that will be used throughout the conventions:

• Pascal Case: Initial caps at the start of each word. Example: PascalCase
• Camel Case: Initial caps at the start of each word except the first. Example: camelCase
• Lower Case: All lower case. Example: lowercase
• Hungarian: Initial type tag in lower case (with possible modifiers), followed by optional Pascal Case basename. Example: strHungarian

Documentation Rules [SA16xx]

Layout Rules [SA15xx]

Maintainability Rules [SA14xx]

Naming Rules [SA13xx]

Ordering Rules [SA12xx]

Readability Rules [SA11xx]

Spacing Rules [SA10xx]

Design Rules

Globalization Rules

Interoperability Rules

Mobility Rules

Naming Rules

Performance Rules

Portability Rules

Security Rules

Usage Rules

Name Spaces

Name Spaces should use Pascal Case. All namespaces for your code should be prefixed by a unique identifier for your organization, followed by a namespace for the application. For example, if your company is DotNetCo and your application is called Btriever, then the namespace for the application should be DotNetCo.Btriever. All code in a project should appear within one of your namespaces.

File Names

There are different naming rules for web applications than Windows applications.

WINDOWS APPLICATIONS: File names should use Pascal Case.

WEB APPLICATIONS: File names must be in Lower Case. If you use Visual Studio to create the file, you will need create the file using Pascal Case, then rename the file to Lower Case. This will make the capitalization of the file and the class within the file to come out correct. Exception: AssemblyInfo.cs, Global.asax, and Web.Config should be left in Pascal Case.

In general, each class should be placed into a separate file, however there are times where having a separate file for a small class becomes unwieldy. The filename should be the same as the class name that is in the file. If there are more than one class in the file, the file name be the same as the most important class in the file. If there are several small classes in the file of equal importance, then the file name should reflect the the group of classes.

Class Names

Class names should use Pascal Case. Since classes are representations of things, the names of classes should represent a noun. For example:

Employee
MayaDate
AppSettingsReader

Interface Names

Interface names should use Pascal Case. Interface names must begin with the letter I. Interface names should be a noun or adjective depending on whether the interface describes an object, such as IAccessControl, or modifies an existing object, such as IAccessible.

Method Names

Method names should use Pascal Case. Since methods are things that you do to an object, in otherwords, a verb, method names should usually start with a verb. For example:

AddMonths()
GetService()
InitializeLifetimeService()

Delegate Names

Delegate names should use Pascal Case.

Event Handler Names

Event Handler names should use Pascal Case. Event Handler names should always end with the suffix EventHandler. Event Handler names should use present or past tense to indicate whether the event is in the process of occuring, or has already occured. For example:

ButtonClickEventHandler
CheckChangeEventHandler
CheckChangedEventHandler
TickEventHandler
ValidatingEventHandler
ValidatedEventHandler

Event Argument Names

Event Arguments names should use Pascal Case. Event Argument names should inherit from System.EventArgs and end in the string EventArgs.

Enum Names

Enum names should use Pascal Case.

Variables

Variables should use Hungarian Case.

Fields and Properties

Fields and Properties names should use Hungarian Case. The base name of the Field or Property should be a noun. The value of the property describes the object, so should typically be an adjective. For example:

Color (values=Red, Blue, Green)
Size (value=400)
Text (value=Some random text)

Line Width

A physical line of code should be no more than 100 characters wide. A logical line longer than this should be broken into multiple physical lines.

A suggestion to maintain this width is to place a comment at the top of each file of code. This comment should be a line of asterisks with a total of 100 characters in it, ending in a | symbol. For example:

[C#]

//**************************************************************************************************|

[Visual basic]

'***************************************************************************************************|

Then size the width of the code window so that the | symbol is just visible. A line of code should be broken into multiple physical lines when the code goes past the window edge.

In a few cases, long literal strings could be longer than 100 characters. The code should be reformulated to construct the string in code from shorter strings. For example:

strName = "A big, long, huge, extremely extremely long, long, long, long very long hugely long, enormously long string"

Should be broken up like this:

[C#]

strName = "A big, long, huge, extremely extremely long, long,"
    + "long, long very long hugely long, enormously long string";

[Visual Basic]

strName = "A big, long, huge, extremely extremely long, long," _
    & "long, long very long hugely long, enormously long string"

Always be careful to preserve spaces from the original string when breaking a string this way. In cases where breaking a string this way is impractical for performance reasons, an alternative such as loading the string from a resource should be considered. A long literal string in the argument to a function call should be placed into a constant, then the constant passed.

Value Data Types

I am currently accepting suggestions for tags for data types. I will definitely supply tags for these data types:

We may or may not supply tags for these data types:

Parenthesis

Parentheses should have no extraneous white space around them. For example:

[C#]
ATestFunction(intParam1, intParam2);

[Visual Basic]
ATestFunction(intParam1, intParam2)

not

[C#]
ATestFunction ( intParam1, intParam2 ); //WRONG

[Visual Basic]
ATestFunction ( intParam1, intParam2 ) 'WRONG

C# Only: The exception is when using control structures that are followed by a value in parenthesese, such as if or while. In these cases, a space should preceed the first parenthesis. For example:

if (intValue == 1)
    System.Console.WriteLine("Value == 1");

not

if(intValue == 1)
    System.Console.WriteLine("Value == 1");

Commas should have no extraneous white space before them, and one space after them. For example:

[C#]
ATestFunction(intParam1, intParam2, intParam3);

[Visual Basic]
ATestFunction(intParam1, intParam2, intParam3)

not

[C#]
ATestFunction(intParam1,intParam2 ,intParam3); //WRONG

[Visual Basic]
ATestFunction(intParam1,intParam2 ,intParam3); //WRONG

Namespaces

Every class should be in an explicitly named namespace. Namespaces should be constructed using the following format:

<company/entity identifier>.<component identifier>[.<subcomponent identifiers>]

The company/entity identifier should be a short word or abbreviation that identifies the company or other entity producing the software. Examples:

Component identifier is a short description of the component the namespace is describing. Examples:

You can then break down the Component into subcomponent namespaces to as many levels deep as necessary.

Examples:

Rdnc.Mayacal.Engine
Rdnc.Mayacal.UserInterface
Microsoft.VisualBasic
Ups.Enroll

In an ASP.NET application, each subdirectory should have its own namespace. For a company named RDNC and a website named Mayacal, the table below shows the directory and the namespace that files in that directory should fall in.

Globals

Every project should included a file called Globals.vb or Globals.cs. This file should contain a class called Globals. This class should contain the Main procedure that starts the program for Windows applications. You will have to move the Main procedure from some other file if you used a Visual Studio template to create the project.

The Globals class can also contain static helper variables and procedures used throughout the rest of the assembly.

Custom Exceptions

If the application throws an exception, it should never any exception from the .NET Framework. Instead it should create its own custom exceptions and throw those. All custom exceptions should inherit from ApplicationException and be placed into a file called Exceptions.vb or Exceptions.cs. For example:

Public Class InvalidFileException
   Inherits System.ApplicationException
   Sub New(ByVal strMessage As String)
      MyBase.New(strMessage)
   End Sub
End Class

public class InvalidFileException: System.ApplicationException
{
    public InvalidFileException(string strMessage): base(strmessage)
    {
    }
}

Simple Types

In VB.NET and C#, the simple types that are integrated in the language map to data types supplied by the .NET Framework. When declaring variables of these simple types, you should use the keyword supplied by the language rather than the .NET Framework type.

Examples:

[C#]
int intValue;
long lngFoo;
uint uintBar;
System.DateTime dtmToday;

[Visual Basic]
Dim intValue As Integer
Dim lngFoo As Long
Dim uintBar As System.UInt32
Dim dtmToday As Date

{Alternative Standard: None of the language integrated data types may be used. Instead only the .NET Framework data types should be used.}

Collections

The names of collections should be the plural of one of the items in the collection. So if you have a class that represents a collection of Employee objects, the name of the collections should be Employees. Be careful when naming classes that will later be put into a collection. You should name the class that describes the specifics of a book Detail, not Details, if you are later going to create a collection of these Detail objects. Or better might be to rename the class altogether, as BookDescription.

Properties that return a collection should be named the same as the collection that they return. For example, a property that returns the Employees collection should be named Employees.

Comment Blocks

Every non-private piece of code should have an XML comment that describes the feature. For more details see the documention of XML Comments. Private code, internal only to the class in which it is defined, is not strictly required to have XML Comments, but is recommended. Although the Visual Basic compiler doesn't parse XML Comments in the current version, you should still add the comments to the source code. The format to use for Visual Basic XML comments is:

'/<summary>
'/This is the summary
'/</summary>

Operators

Binary operators, such as +, should have a space placed on either side of them. Unary operators should have no extra space between the operator and the thing that they operate on. For example:

intFoo + intBar
intFoo ^ intBar
intFoo++
intFoo * -6

Imports and Using Statements

A Imports statement in Visual Basic and a using statement in C# allows the programmer to avoid having to include the complete namespace before a class name. Imports and using statements, however, are at the expense of explicitness in the code. They can also cause ambiguity of class names if there are two classes with the same name in two different namespaces. (The compiler will complain if there is any ambiguity.)

It is never wrong to include the complete namespace before a class name. However, if the complete namespace is used one place in a file, then it should always be used in that file. Strive to be consistent within a particular file.

If there is more than one Imports or using statement in a file, then they should be alphabetized. For example:

[Visual Basic]
Imports System
Imports System.ComponentModel
Imports System.Diagnostics
Imports System.Drawing
Imports System.IO
Imports System.Web
Imports System.Windows.Forms
Imports System.Xml
Imports Xoc.Header

[C#]
using System;
using System.ComponentModel;
using System.Diagnostics;
using System.Drawing;
using System.IO;
using System.Web;
using System.Windows.Forms;
using System.Xml;
using Xoc.Header;

Imports and using statements that, due to code maintenance, are no longer in use should be removed. After a major rewrite, it is recommended to comment out all the Imports or using statements and recompile. Any that are complained about by the compiler should be commented back in, until the program compiles. Any that are still commented out at that point should be removed.

In Visual Basic, project level imports can be specified in the Project Properties dialog. These should not be used, and any default ones should be removed.

{Alternative Standard: Imports and using statements should not be used.}

Declarations

Each variable should be declared on its own line. For example:

[Visual Basic]
Dim intValue As Integer
Dim intAnother As Integer
Dim strResult As String

[C#]
int intValue;
int intAnother;
string strResult;

[Visual Basic]
Dim intValue, intAnother As Integer, strResult As String 'Wrong

[C#]
integer intValue, intAnother; //Wrong

Dim intValue, intAnother As Integer

Comments

A comment is placed into the code to help clarify what the intention of the code is. Each comment may be placed onto a line by itself or at the end of an existing line of code. A comment at the end of a line of code should be use in only a few places:

• The end of a variable declaration line.

All other comments should be placed on a separate line above the line they are documenting and indented to the same level. A comment of this sort is generally preceded by a blank line unless it is the first line of an indented block. For example: vt = vti.VarType 'Special hack for analyzing my code If LCase$(Left$(strParamName, Len(strcDecPrefix))) = strcDecPrefix Then strDataType = strDecimal End If If it is the first line of an indented block, it is not preceded by a blank line. For example: If mboolShowProperties Then 'Show properties for each member For Each mi In ci.Members Comments should state the intention of the code not how it performs the task. This is an example of a worthless comment: 'Place the VarType into the vt variable vt = vti.VarType It is worse than no comment at all. The comment is wrong if the code changes to use the variable name vtCur instead of vt without changing the comment. When reading a comment that doesn't match the code, the question becomes whether the comment is correct or the code is correct. Usually it is the comment that is wrong, but it may take some time to prove that. In general, do not write comments that have to be maintained, because in the real-world people frequently do not maintain comments. A comment that states the intention of the code, though, may be useful. For example: 'Store VarType for recovery in error condition. vt = vti.VarType However, use these comments only when the intention is not immediately clear when reading the code. Instead strive to make the code self explanatory, through good naming and coding conventions.

Methods

Methods must always be followed by arguments in parentheses. If the method takes no arguments, it must be followed by ().

Assertions

Indenting

Deprecated Features

Runtime Error Handling

AssemblyInfo

Attributes

Attributes should be placed on a line by themselves preceding the thing they modify. If there is more than one attribute, they should each be surrounded by their delimiters (<> in Visual Basic .NET, and [] in C#), rather than using a comma separated list of the attributes. Attributes should be listed in alphabetical order. Attributes that take no arguments should be followed by (). For example:

[C#]
	[CLSCompliant(false)]
	[ComImport()]
	[Guid("000214F2-0000-0000-C000-000000000046")]
	[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
	public interface IEnumIDList
	...
[Visual Basic]
	<CLSCompliant(false)> _
	<ComImport()> _
	<Guid("000214F2-0000-0000-C000-000000000046")> _
	<InterfaceType(ComInterfaceType.InterfaceIsIUnknown)> _
	public interface IEnumIDList
	...

Summary

The Reddick .NET Conventions make your code easier to read, easier to maintain, more reliable, and faster.