Coding Techniques

Introduction

Coding techniques incorporate many facets of software development and, although they usually have no impact on the functionality of the application, they contribute to an improved comprehension of source code. For the purpose of this document, all forms of source code are considered, including programming, scripting, markup, and query languages.

The coding techniques defined here are not proposed to form an inflexible set of coding standards. Rather, they are meant to serve as a guide for developing a coding standard for a specific software project.

The coding techniques are divided into three sections:

• Names
• Comments
• Format

Names

Perhaps one of the most influential aids to understanding the logical flow of an application is how the various elements of the application are named. A name should tell "what" rather than "how." By avoiding names that expose the underlying implementation, which can change, you preserve a layer of abstraction that simplifies the complexity. For example, you could use GetNextStudent() instead of GetNextArrayElement().

A tenet of naming is that difficulty in selecting a proper name may indicate that you need to further analyze or define the purpose of an item. Make names long enough to be meaningful but short enough to avoid being wordy. Programmatically, a unique name serves only to differentiate one item from another. Expressive names function as an aid to the human reader; therefore, it makes sense to provide a name that the human reader can comprehend. However, be certain that the names chosen are in compliance with the applicable language's rules and standards.

Following are recommended naming techniques:

Routines

• Avoid elusive names that are open to subjective interpretation, such as Analyze() for a routine, or xxK8 for a variable. Such names contribute to ambiguity more than abstraction.
• In object-oriented languages, it is redundant to include class names in the name of class properties, such as Book.BookTitle. Instead, use Book.Title.
• Use the verb-noun method for naming routines that perform some operation on a given object, such as CalculateInvoiceTotal().
• In languages that permit function overloading, all overloads should perform a similar function. For those languages that do not permit function overloading, establish a naming standard that relates similar functions.

Variables

• Append computation qualifiers (Avg, Sum, Min, Max, Index) to the end of a variable name where appropriate.
• Use customary opposite pairs in variable names, such as min/max, begin/end, and open/close.
• Since most names are constructed by concatenating several words together, use mixed-case formatting to simplify reading them. In addition, to help distinguish between variables and routines, use Pascal casing (CalculateInvoiceTotal) for routine names where the first letter of each word is capitalized. For variable names, use camel casing (documentFormatType) where the first letter of each word except the first is capitalized.
• Boolean variable names should contain Is which implies Yes/No or True/False values, such as fileIsFound.
• Avoid using terms such as Flag when naming status variables, which differ from Boolean variables in that they may have more than two possible values. Instead of documentFlag, use a more descriptive name such as documentFormatType.
• Even for a short-lived variable that may appear in only a few lines of code, still use a meaningful name. Use single-letter variable names, such as i, or j, for short-loop indexes only.
• If using Charles Simonyi's Hungarian Naming Convention, or some derivative thereof, develop a list of standard prefixes for the project to help developers consistently name variables. For more information, see "Hungarian Notation."
• For variable names, it is sometimes useful to include notation that indicates the scope of the variable, such as prefixing a g_ for global variables and m_ for module-level variables in Microsoft Visual Basic®.
• Constants should be all uppercase with underscores between words, such as NUM_DAYS_IN_WEEK. Also, begin groups of enumerated types with a common prefix, such as FONT_ARIAL and FONT_ROMAN.

Tables

• When naming tables, express the name in the singular form. For example, use Employee instead of Employees.
• When naming columns of tables, do not repeat the table name; for example, avoid having a field called EmployeeLastName in a table called Employee.
• Do not incorporate the data type in the name of a column. This will reduce the amount of work needed should it become necessary to change the data type later.

Microsoft SQL Server

• Do not prefix stored procedures with sp_, because this prefix is reserved for identifying system-stored procedures.
• In Transact-SQL, do not prefix variables with @@, which should be reserved for truly global variables such as @@IDENTITY.

Miscellaneous

• Minimize the use of abbreviations. If abbreviations are used, be consistent in their use. An abbreviation should have only one meaning and likewise, each abbreviated word should have only one abbreviation. For example, if using min to abbreviate minimum, do so everywhere and do not later use it to abbreviate minute.
• When naming functions, include a description of the value being returned, such as GetCurrentWindowName().
• File and folder names, like procedure names, should accurately describe what purpose they serve.
• Avoid reusing names for different elements, such as a routine called ProcessSales() and a variable called iProcessSales.
• Avoid homonyms when naming elements to prevent confusion during code reviews, such as write and right.
• When naming elements, avoid using commonly misspelled words. Also, be aware of differences that exist between American and British English, such as color/colour and check/cheque.
• Avoid using typographical marks to identify data types, such as $ for strings or % for integers.

Comments

• Software documentation exists in two forms, external and internal. External documentation is maintained outside of the source code, such as specifications, help files, and design documents. Internal documentation is composed of comments that developers write within the source code at development time.
• One of the challenges of software documentation is ensuring that the comments are maintained and updated in parallel with the source code. Although properly commenting source code serves no purpose at run time, it is invaluable to a developer who must maintain a particularly intricate or cumbersome piece of software.
• Following are recommended commenting techniques:
• When modifying code, always keep the commenting around it up to date.
• At the beginning of every routine, it is helpful to provide standard, boilerplate comments, indicating the routine's purpose, assumptions, and limitations. A boilerplate comment should be a brief introduction to understand why the routine exists and what it can do.
• Avoid adding comments at the end of a line of code; end-line comments make code more difficult to read. However, end-line comments are appropriate when annotating variable declarations. In this case, align all end-line comments at a common tab stop.
• Avoid using clutter comments, such as an entire line of asterisks. Instead, use white space to separate comments from code.
• Avoid surrounding a block comment with a typographical frame. It may look attractive, but it is difficult to maintain.
• Prior to deployment, remove all temporary or extraneous comments to avoid confusion during future maintenance work.
• If you need comments to explain a complex section of code, examine the code to determine if you should rewrite it. If at all possible, do not document bad code—rewrite it. Although performance should not typically be sacrificed to make the code simpler for human consumption, a balance must be maintained between performance and maintainability.
• Use complete sentences when writing comments. Comments should clarify the code, not add ambiguity.
• Comment as you code, because most likely there won't be time to do it later. Also, should you get a chance to revisit code you've written, that which is obvious today probably won't be obvious six weeks from now.
• Avoid the use of superfluous or inappropriate comments, such as humorous sidebar remarks.
• Use comments to explain the intent of the code. They should not serve as inline translations of the code.
• Comment anything that is not readily obvious in the code.
• To prevent recurring problems, always use comments on bug fixes and work-around code, especially in a team environment.
• Use comments on code that consists of loops and logic branches. These are key areas that will assist the reader when reading source code.
• Separate comments from comment delimiters with white space. Doing so will make comments stand out and easier to locate when viewed without color clues.
• Throughout the application, construct comments using a uniform style, with consistent punctuation and structure.

Format

Formatting makes the logical organization of the code stand out. Taking the time to ensure that the source code is formatted in a consistent, logical manner is helpful to yourself and to other developers who must decipher the source code.

Following are recommended formatting techniques:

• Establish a standard size for an indent, such as four spaces, and use it consistently. Align sections of code using the prescribed indentation.
• Use a monospace font when publishing hard-copy versions of the source code.
• Except for constants, which are best expressed in all uppercase characters with underscores, use mixed case instead of underscores to make names easier to read.
• Align open and close braces vertically where brace pairs align
• Establish a maximum line length for comments and code to avoid having to scroll the source code window and to allow for clean hard-copy presentation.
• Use spaces before and after most operators when doing so does not alter the intent of the code. For example, an exception is the pointer notation used in C++.
• Put a space after each comma in comma-delimited lists, such as array values and arguments, when doing so does not alter the intent of the code. For example, an exception is an ActiveX® Data Object (ADO) Connection argument.
• Use white space to provide organizational clues to source code. Doing so creates "paragraphs" of code, which aid the reader in comprehending the logical segmenting of the software.
• When a line is broken across several lines, make it obvious that the line is incomplete without the following line.
• Where appropriate, avoid placing more than one statement per line. An exception is a loop in C, C++, Visual J++®, or JScript®, such as for (i = 0; i < 100; i++).
• When writing HTML, establish a standard format for tags and attributes, such as using all uppercase for tags and all lowercase for attributes. As an alternative, adhere to the XHTML specification to ensure all HTML documents are valid. Although there are file size trade-offs to consider when creating Web pages, use quoted attribute values and closing tags to ease maintainability.
• When writing SQL statements, use all uppercase for keywords and mixed case for database elements, such as tables, columns, and views.
• Divide source code logically between physical files.
• In ASP, use script delimiters around blocks of script rather than around each line of script or interspersing small HTML fragments with server-side scripting. Using script delimiters around each line or interspersing HTML fragments with server-side scripting increases the frequency of context switching on the server side, which hampers performance and degrades code readability.
• Put each major SQL clause on a separate line so statements are easier to read and edit

Reference: MSDN