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
UNDERDEVELOPMENT
PORTION
RHTML Guidelines
totally no @ variables in partials, all locals
