bildr:Code Style Guide

Coding Basics

Always remember that the code should be easy to read and understand. Write your code thinking of others.

Variable use and definition

When creating or using variables in your code, please use descriptive variable names and hold back on the use of acronyms and abbreviations. Camel-text is a well known form of writing variable names and methods ( long variable names are a terrible idea, this just shows readability of a camel-text):
lowerCaseFirstLetterOfFirstWordThenCapitalizeFirstLetterOfFollowingWords
Examples:
sessionName or session_name NOT sName or sessn, isHistoryFile NOT isHist

One exception to this rule is in the use of constants. As a general rule constants or preprocessor directives should be in full capitals separated if necessary with underscores to help distinguish them from normal variables.
Examples:
#define F_CPU 16000000
const int FILES = 10;

Commenting and spacing your code

Always remember that the someone reading your code may not understand what is going on. Please add quality comments to your code, and remember add line breaks when needed to increase legibility. Try to keep lines short, as a rule of thumb 80 characters is the maximum length for a line, this helps users read code without having to scroll horizontally back and forth.

case 'getHistoryItem':
//----------------------------------------------------------------------------
// get the history of a file
//----------------------------------------------------------------------------
	
	getHistoryItem($options['version_id']);
		
break;

Method Commenting

Good source code comments are important in writing software, especially when documenting methods. Methods are a sub routine in software that accomplish a specific task. Methods usually have a form of input (pre-conditions) and an output (post-conditions). Depending on the programming language type strength, these inputs and outputs usually conform to a specific datatype (i.e uint8_t, float, double, etc...). These inputs and outputs need to be defined in comments to inform you and/or any developer using your code. In addition to avoiding issues pertaining to type errors, it is important to document a summary of what your procedure will accomplish. Following a well defined summary, it is good practice to document anything unusual that the procedure might perform. A good example of commented method is as follows:

/*
 * @author: Joe Smith <joesmith@domain.com>
 *
 * @summary: This will perform some type of operation on variable one and variable two, and 
 * return a result modified by however I explain it
 *
 * @input: uint8_t variableOne, float variableTwo
 *
 * @output: uint8_t result
 *
 * @note: This method might do something unexpected to the result. 
 */
uint8_t DoSomething(uint8_t variableOne, float variableTwo)
{
     uint8_t resultValue;
     ...
     ...
     return resultValue;
}

It is also a good idea to give credit to algorithms that you take from other sources. The author section of the comment is a great place to state other authors of the algorithm.

This page is an Article on bildr. Articles are pages that define or explain a concept, method, or generic item.