Writing readable code

Casing standards Before we discuss proper ways of naming different program elements, let’s define the two most common ways of using character casing (UPPER and lower case) to distinguish between elements. They are:

• Pascal casing—The first character is upper case, and the first letter of each word in the object is also upper case, e.g. InvoiceNumber or PrintInvoice. All other characters are lower case.
• Camel casing—The first character is not upper case, but the first letter of each word in the object is upper case, e.g. invoiceNumber. All other characters are lower case.

Unfortunately, using casing to distinguish between elements can cause problems in languages that are not case sensitive. For example, because C# is case sensitive, you can call a private variable employee and then have a public property called Employee that’s used by callers. This is perfectly legal. But in Visual Basic, you'd get an error because it’s not case sensitive—it sees both as the same variable. If you have a mixed language environment, you’ll need guidelines for developers using either language to read each other’s code.

Naming standards
Assuming that we’ll use these casing standards, let’s look at some simple recommendations for common program elements, as well as some samples.

Classes
Some classes are designed to mimic real world objects. For these, the names chosen should reflect the real world object and be singular nouns like Employee, Invoice, or Timecard. For internal classes, use Pascal casing and make the resulting class name singular like ThreadPool or CustomColor. Classes should be singular so that they can be represented as plural for collection names, e.g. an array of Employees.

Class members
Developers using C# and other case sensitive language should name their class members using camel casing. This makes it simple for them to distinguish between the internal variable name and the public property Name. Many VB developers prefer to use a form of Hungarian notation for a class member that attaches a prefix that indicates the variable type to the variable name, e.g., sName means a variable called Name of type string. I don’t think this is necessary when you’re using advanced development environments like VS.NET in which you can hover over any variable to determine its type. I prefer to prefix all of my class member names with a lower case m. This way all of the internal variables holding internal class information have the same m prefix and all public properties have the name itself—an internal variable mName represents the public property Name.

Methods
You should name methods using Pascal casing and in a way that describes the work they perform. For example, the method that adds employees to the database should be called AddEmployee, or the invoice printing method should be called PrintInvoice. If methods return a Boolean value, the method name should begin with a verb so that its use in an If statement is more obvious. For example, if you have a method that determines whether an employee is eligible for the company 401k plan, call it IsEligible401k so that when used in an If statement, it reads, If IsEligible401k then…

Method arguments, return values, and variables
All method arguments, return values, and variables should be named using Pascal casing and, like method names, should reflect what the argument or variable represents. This is especially important for method arguments since Intellisense will return the argument name and type when you’re making the method call. A descriptive name and the type expected should be all a developer using your method needs to understand the values he or she should provide.

Controls
Control naming is another point of contention for many development shops. Although most agree that they shouldn’t use default names like TextBox1 or Label1 one, they disagree on whether to name the control like a variable or to use a prefix indicating the control type. I prefer to use a standard set of three-letter prefixes to name all of the controls on a form. For example, call the text boxes that store the first and last name txtFirstName and txtLastName, respectively. Command buttons to process data on the form can be called cmdSubmit or cmdCancel. Just make sure you’re consistent and the standards are well understood.

Adding comments
Commenting code is a necessary evil to most developers. In order to teach proper commenting techniques, I often comment code that I write in demonstrations. To make the commenting process easier, I recommend that developers write comments first to describe the code they intend to write. First I write a comment to describe what a procedure, class, or other program element does—but not how it does it. Then I write a series of comments that describe each major step of a process or element of a class. After writing the code that defines the class or describes the process in a procedure, I document the details of each external variable, control, open file, or other element accessed by the procedure and give a short description of each input argument and the return values.

If you’re developing code in C#, the VS.NET environment has a built-in tool that allows you to turn internal C# comments into an external HTML document. You can place special processing directives in your comments that change the way the external document is rendered. For more information, check the internal VS.NET help file: ms-help://MS.VSCC/MS.MSDNVS/csref/html/vcoriXMLDocumentation.htm.

Following a few simple naming conventions and documentation standards simplifies team code maintenance. Try these techniques on your next project and see if they work for you.