CodingStandards

Amdroid-h Coding Standards

Revision: Pre First Draft

Introduction

Rather than stick a spiffy license to this document, I'm going to release this set of Coding Standards into Public Domain. So feel free to do what you like with it. Any comments that are made below the document, are copyright of their respective owners.

The goal of this document is to provide a consistent, well organized, easy to read format of coding. As my expertise is more within the C/C++ realm, that will be the focus with an extension into Java.
These standards are guidelines, not rules, in writing source code, as there are always exceptions that creep up and throw off even the most comprehensive of coding standards.

Rule 1: The Only Rule

If the code you have written is very hard to read, but follows all of the rules (i.e. looks really bad). Format the code to something that is easier to read. That’s it!

This rule can be applied to any of the guidelines in this document.

Project Organization

File Names

File names have no character limit, and can be a mix of upper/lower case alphanumeric characters including underscores (Note: All upper case names look bad).
The usage of numbers is unrestricted, and should be used whenever it makes sense.

File organization/naming has 4 steps and should be escalated in this order:

  1. Single name
  2. Multiple name camel case (e.g. TestCase)
  3. Subdirectories (eg. Tests/TestCase)
  4. Underscores (eg. Tests/HaaTa_TestCase)

File Extensions

File extensions should be in lower case

  • java – Java source file
  • cpp – C++ source file
  • h – C++ header file
  • xml – XML file

Directory Structure

Basic Text Formatting

This is probably the most important part of the coding standards guide, as it outlines what to do in general cases.

Tabbing/Indentation

Probably one of the more debated subjects, mostly due to the improper use of the ‘tab’ character.

All indentation should be done with the ‘tab’ character. Under no circumstances should spaces be used for indentation, except to line up variables and equations on multi-line wraps:


public void function()
{



if ( test == 5
  || test <  2 )
{
    test = 0;
    func2();
}




}

However, to line code or comments up to the right of the indentation, ‘tab’ characters should not be used, ever:


public void function()
{



// Check test variable
// test  - First test
// test2 - Second test
// tst   - Quick test
if ( test == 5
  || test <  2 )
{
    test = 0;
    func2();
}




}

Column Limit

The soft column limit is 100 characters wide. If necessary it can be exceeded; however code usually becomes harder to read at that point, so a multi-line command should be used. 120 characters may still be ok, depending on the code used.

If you are running into this problem because of nested loops or functions, you've been nesting too many loops or functions, and need to rethink the code structure.

Brackets

Bracket: ( )

In general should include spaces after opening and closing the brackets:


if ( test == 5 )

If there is nothing within the brackets, the space should be omitted:


function();

If the contents of the brackets use an additional separator like quotes “ ” then the space may be omitted:


string(“Here is a string”);

However, if there are multiple parameters, then the space must still be included:


string( “Here is a string %d”, variable );

One special case where a space is never used is with C-Style casting:


double number = (double)integerNumber;

Bracket: [ ]

General case, a space must be used to separate the brackets from the data:


array[ function( 2 ) ]

If there is only a string or char used then the space may be omitted:


arr1y[“test”]
arr2y[‘c’]

Bracket: { }

There must always be a space/tab/newline on both sides of each { or } brackets. No exceptions.

Quotation/Strings

The only special case with strings is with brackets, which is covered in the previous section.

Note: Be localization friendly! Never concatenate UI strings using +.

Formulas

When writing any sort of mathematical formula, no matter how simple, it is important that it is easy to read.

Use brackets to increase readability only. Excessive brackets usually impede the reader rather than help them.
In the general case, use as few brackets as possible.

A space before/after every term. No exceptions.

Multi-line formulas are left up to the implementer. The only thing to remember is that the same number of tab characters is to be used for each line. Any additional lining up should be done using spaces.

Condition Statements

You can think of condition statements like Formulas. All the same rules apply to the conditions.
Brackets only as necessary, but enough not to cause compiler warnings. Spaces before/after every term.

Multi-line formulas are left up to the implementer. The only thing to remember is that the same number of tab characters is to be used for each line. Any additional lining up should be done using spaces.

Header Files

Outline

Includes/Imports

Multiple Inclusion

Function Naming

Outline

Documentation

Function

Class

Structure

Enumeration

XML

Programming Conventions

Macros

Defines

Return Values

Identifiers

Debugging Code

Outline

Testing Suites

Outline

Comments

Do not post comments until the first draft is complete