Thursday, May 8, 2008

Coding Standards and Guidelines

I was asked to create a coding standards document where I work. Oh yeah, I did not do it because I love to do this kind of work. So I outsourced by job to my best friend Google ;-) I got several hits. I compiled a coding standards and guidelines document with the help my buddy. I would like to give it back to from where I got. So here it is:

Coding Standards

1. Introduction

Application developers need to adhere to certain coding standards in order to enhance the readability and maintainability of the application.

Well written software offers many advantages. It will contain fewer bugs and will run more efficiently than poorly written programs. Since software has a life cycle and much of which revolves around maintenance, it will be easier for the original developer(s) and future keepers of the code to maintain and modify the software as needed. This will lead to increased productivity of the developer(s). The overall cost of the software is greatly reduced when the code is developed and maintained according to software standards.

This guide makes a distinction between standards and guidelines. Standards are rules which programmers are expected to follow. Guidelines can be viewed as suggestions which can help programmers write better software and are optional, but highly recommended.

2. Internal Documentation Standards

If done correctly, internal documentation improves the readability of a software module. A file containing one of more software modules should have comment block at its beginning containing the following basic information:

The name of the author who created the file

The date the file was created

The author’s development group

Description (overview of the purpose of the modules)

Note that a module is a method, function, or subroutine.

Each module contained within the source file should be preceded by a block of comments showing the following:

The name of the module

The name of the original author (if the module author is different than the author of the file.)

The date the module was created

A description of what the module does

A list of the calling arguments, their types, and brief explanations of what they do

A list of required files and/or database tables needed by the routine, indicating if the routine expects the database or files to be already opened

Return values

Error codes/exceptions

3. Coding Standards

3.1 Indentation:

Proper and consistent indentation is important in producing easy to read and maintainable programs. Indentation should be used to:

Emphasize the body of a control statement such as a loop or a select statement

Emphasize the body of a conditional statement

Emphasize a new scope block

Tabs should be used for indentation.

Examples:

/* Indentation used in a loop construct. */

for (int i = 0; i < number_of_employees; ++i)

{

total_wages += employee[i].wages;

if (total_wages > 1,000,000)

{

System.out.println(“Over one million”);

}

}

// Indentation used in the body of a method.

package void get_vehicle_info ( )

{

System.out.println ( “VIN: “ + vin ) ;

System.out.println ( “Make: “ + make ) ;

System.out.println ( “Model: “ + model ) ;

System.out.println ( “Year: “ + year ) ;

}

3.2 Inline Comments

Inline comments explaining the functioning of the subroutine or key aspects of the algorithm shall be frequently used.

Inline comments should be used to make the code clearer to a programmer trying to read and understand it. Writing a well structured program lends much to its readability even without inline comments. The bottom line is to use inline comments where they are needed to explain complicated program behavior or requirements. Use inline comments to generalize what a block of code, conditional structure, or control structure is doing. Do not use overuse inline comments to explain program details which are readily obvious to an intermediately skilled programmer.

3.3 Structured Programming

Structured (or modular) programming techniques shall be used. GO TO statements shall not be used as they lead to “spaghetti” code, which is hard to read and maintain

3.4 Classes, Subroutines, Functions, and Methods

Keep subroutines, functions, and methods reasonably sized. This depends upon the language being used. A good rule of thumb for module length is to constrain each module to one function or action (i.e. each module should only do one “thing”). If a module grows too large, it is usually because the programmer is trying to accomplish too many actions at one time.

The names of the classes, subroutines, functions, and methods shall have verbs in them. That is the names shall specify an action, e.g. “getName”, “computeStatistics”.

3.5 Source Files

The name of the source file or script shall represent its function. All of the routines in a file shall have a common purpose.

3.6 Variable Names

Variable shall have mnemonic or meaningful names that convey to a casual observer, the intent of its use. Variables shall be initialized prior to its first use. Variable names shall be defined in Pascal Case (e.g. getUserInfo, setMemberProfile).

3.7 Use of Braces

In some languages, braces are used to delimit the bodies of conditional statements, control constructs, and blocks of scope. Programmers shall use the following bracing style:

for (int i = 0 ; i < 100; i++)

{

/* Some work is done here. */

}

Braces shall be used even when there is only one statement in the control block. For example:

Bad:

if (i <= 0)

printf (“Positive number required.\n”);

Better:

if (i <= 0)

{

printf (“Positive number required.\n”);

}

4. Coding Guidelines

General coding guidelines provide the programmer with a set of best practices which can be used to make programs easier to read and maintain.

4.1 Line Length

It is considered good practice to keep the lengths of source code lines at or below 80 characters. Lines longer than this may not be displayed properly on some terminals and tools.

4.2 SpacingThe proper use of spaces within a line of code can enhance readability. Good rules of thumb are as follows:

A keyword followed by a parenthesis should be separated by a space.

A blank space should appear after each comma in an argument list.

All binary operators except “.” should be separated from their operands by spaces. Blank spaces should never separate unary operators such as unary minus, increment (“++”), and decrement (“—“) from their operands.

4.4 Program StatementsProgram statements should be limited to one per line. Also, nested statements should be avoided when possible.Examples:Bad:number_of_names = names.length ; b = new JButton [ number_of_names ] ;

4.5 Use of ParenthesesIt is better to use parentheses liberally. Even in cases where operator precedence unambiguously dictates the order of evaluation of an expression, often it is beneficial from a readability point of view to include parentheses anyway.Example:

Acceptable:total = 3 – 4 * 3 ;

Better:total = 3 – ( 4 * 3 ) ;

4.6 Coding for Efficiency vs. Coding for ReadabilityThere are many aspects to programming. These include writing software that runs efficiently and writing software that is easy to maintain. These two goals often collide with each other. Creating code that runs as efficiently as possible often means writing code that uses tricky logic and complex algorithms, code that can be hard to follow and maintain even with ample inline comments.

The programmer needs to carefully weigh efficiency gains versus program complexity and readability. If a more complicated algorithm offers only small gains in the speed of a program, the programmer should consider using a simpler algorithm. Although slower, the simpler algorithm will be easier for other programmers to understand.

4.7 Meaningful Error MessagesError handling is an important aspect of computer programming. This not only includes adding the necessary logic to test for and handle errors but also involves making error messages meaningful. Error messages should also be stored in way that makes them easy to review.

Secure Coding Guidelines

Protecting access to your data source is one of the most important goals when working on the security of your application. To help limit access to your data source it is imperative to keep connection information such as Username, Password, data source name, etc. private.

1. Read Only DB User

Applications code must connect to the database as a database user who has read only access to the data and can’t update or change any data or objects. Only where necessary (such as admin pages that require update or insert) connect as another user who has limited privileges to write to only the required database objects. Also strongly consider using Windows Integrated Authentication to access SQL Server in your code. If it can’t be used for any reason, avoid storing clear text password instead store the password encrypted.

2. Validating Inputs

Before using the HTTP inputs provided by end users in a database query, validate them using regular expressions or other means. For example, the following ensures that a userid value is an 8-character alphanumeric string.

3. Using Parameters (Prepared Statements)

Parameters provide a convenient method for organizing values passed with a SQL statement or to a stored procedure. Additionally, parameters can guard against a SQL Insertion attack by ensuring that values received from an external source are passed as values only, and not part of the SQL statement. As a result, SQL commands inserted into a value are not executed at the data source. Rather, the values passed are treated as a parameter value only. The following code shows an example of using a parameter to pass a value.

4. Keep Exception / Server Error Information Private

Attackers often use information from an exception, such as the name of your server, database, or table to mount a specific attack on your system. Because exceptions can contain specific information about your application or data source, you can help your application and data source better protected by only exposing information to the client that is required.

Use friendly error messages such as “Database Connection failed. Please contact the Customer Support at support@company.com”. Do not display the server errors or the Exception stack to the end user in production environments.