Coding Standard Document - code formatting guidelines

Coding Standard Document

Version 0.1

General source code formatting guidelines

Indentation: Indenting is two spaces per level. Do not use tab characters for indentation. Make sure you indent your code properly.

Line lengths: Lines in a source file must never have more than 80 characters. When a complete statement or an expression will not fit on a single line, break it according to these general principles: 

Break after a comma. 

Break before an operator. 

Align the new line with the beginning of the expression at the same level on the previous line. 

If the above rules lead to confusing code or to code that's squished up against the right margin, just indent one additional level instead. 

Comments: comments are a must. You should provide proper comments in you code. Comments must be given before the code and not after it.

do..end: do statement always appears on its own line so that the do statement always appears indented on the same level as the corresponding statement.

array.each do               # incorrect do statement, on same line as each   array.each                    # correct do statement do

Also end statement always appears on its own line indented at the same level as the corresponding do statement.

Code blocks: for code blocks always use parenthesis rather then do..end pair. Openingparenthesis shall be on the same line as corresponding statement and statements of code block shall start from the next line. Also closing parenthesis always appears on its own line.

array.each                    # incorrect, don’t use do..end statement do ……. End   array.each {                  # correct, use parenthesis for code blocks ……. }

Parenthesis: Always use parenthesis. There shall never be white space between an open parenthesis and the next character. Likewise, there shall never be white space between a closed parenthesis and the previous character.

my_function  (param)                # incorrect, no white spaces before opening parenthesis my_function(param)                  # correct

Also there shall be no space between opening parenthesis and its corresponding statement.

my_function( param )                # incorrect, no white spaces after opening and   before closing parenthesis my_function(param)                  # correct

Naming guidelines

Function names: function names shall always be lowercased (no exceptions) and words in function names are separated by an underscore. Always give meaningful names to functions.

SomeFunctionName(params)                # incorrect, no capital letters somefunctionname(params)                              #also incorrect some_function_name(params)                  # correct, all letters in lowercase and words separated through underscore

Variable names: variables are named similarly to functions. Strictly follow ruby conventions for naming variables.

Global Variables: Use of global variables is not allowed. However, they may be used to represent constant values only. Constant names should be all-caps. Keep these constants in a file named constants.rb in PROJECT_ROOT/lib.

Arrays and Hashes: Arrays and hashes must be declared before they are used. Array names must be meaningful plural nouns. Hash names must be meaningful with _hash appended at the end e.g. units_hash

units=[]                             # array declaration   units_hash={}                    # hash declaration

Control Statements

if..else statement

The most likely case to execute in an if..else statement shall be placed under if clause, with less likely cases residing in the else or elsif clause(s).

Try to avoid chaining if statements and case statements.

Do not nest if statements more than five levels deep. Create a clearer approach to the code

If multiple conditions are being tested in an if statement, conditions should be arrange from left to right in order of least to most computation intensive. This improves performance by taking advantage of short-circuit Boolean evaluation logic.

The else/elsif clause shall always be aligned with the corresponding if clause.

case statement

Try using case statements wherever possible as they are logically clearer then if and elsif statements.

The action statements of each case should be kept simple and generally not exceed four to five lines of code. If the actions are more complex, the code should be placed in a separate function.

The use of the else clause of a case statement should be used only for legitimate defaults.

All when statements inside case should be indented at the same level as case statement. For code inside when statement should follow the normal indentation rules.

while and until statements

Avoid exiting the loop with break or raise statements; when possible, you should exit the loop using only the loop condition.

All initialization code for a while loop should occur directly before entering the while loop and should not be separated by other non-related statements.

Any ending housekeeping shall be done immediately following the loop.

for statement

for statements should be used in place of while statements when the code must execute for a known number of times.

Avoid exiting the loop with break or raise statements; when possible, you should exit the loop using only the loop condition.

all other statements

all other statements should follow general formatting guide lines

Exception Handling Guidelines

Exception handling should be used abundantly for both error correction and resource protection. This means that in all cases where resources are allocated, a begin..rescue must be used to ensure proper deallocation of the resource.

Whenever using rescue, try to provide proper error message.

Always provide else clause for default exception handling for all unhandled exception

Always log all exceptions using $@[0].to_s+" "+$!.to_s

Avoid using retry statement

HTML Guidelines

Always mention the doctype. Always use following as DOCTYPE of every html page or layout <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN""DTD/xhtml1-transitional.dtd">. Remeber that DOCTYPE is the first line in an html page.

Always use the following html tag <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

All tags must be in lower case. Only exception to this rule is the DOCTYPE tag which must be in uppercase.

Make sure your html has a valid structure. People commonly make mistakes in the document structure which makes it impossible to make a website appear similar on every browser. Your html is invalid if tags are not in First Opened Last Closed order. All html should be validated by the standard w3 validator

Attribute quotes are mandatory. Every opening quote must have a closing quote e.g. style=font-weight: bold is invalid, always use style=”font-weight: bold”

Every tag must be closed. This means <br> is no more allowed use <br/> or <br></br> instead, same goes for <img> and all other tags which are usually left open.

RHTML Guidelines

Allways write comments in HTML way i.e. <!--this is a comment-->. Never write comments as <%#this is not right way to comment in RHTML%>

Do not leave any leading or trailing spaces in <%%>

References

http://www.econos.de/delphi/cs.html

http://www.cs.rit.edu/~f2y-grd/java-coding-standard.html

http://www.codeproject.com/html/htmltoxhtml.asp

UNDERDEVELOPMENT PORTION

RHTML Guidelines
totally no @ variables in partials, all locals