Project:
Cold Watch
Document: Coding Policy
Version 1.00
Usman Alam
Version:
Error! Unknown
document property name.0
Date: 2011-10-08
Coding Policy
Revision History
Date
2011-10-08
Version
1.00
Description
First Version
Author
Usman Alam
Doc. No.:
Page 2
Usman Alam
Version:
Error! Unknown
document property name.0
Date: 2011-10-08
Coding Policy
Table of Contents
COLD WATCH ................................................................................... ERROR! BOOKMARK NOT DEFINED.
CODING POLICY ............................................................................................................................................... 1
VERSION 1.00 ...................................................................................................................................................... 1
TABLE OF CONTENTS ..................................................................................................................................... 3
1.
INTRODUCTION ........................................................................................................................................ 4
1.1
1.2
1.3
1.4
2.
WHY CODING STANDARDS ARE IMPORTANTS .............................................................................. 5
2.1
2.2
2.3
2.4
3.
PURPOSE OF THIS DOCUMENT .................................................................................................................. 4
DOCUMENT ORGANIZATION..................................................................................................................... 4
TARGET AUDIENCE .................................................................................................................................. 4
REFERENCES............................................................................................................................................ 4
CODE CONSISTENCY ................................................................................................................................ 5
AVOID RISK .............................................................................................................................................. 5
UNDERSTANDABLE OF OTHERS ................................................................................................................ 5
PRODUCT ................................................................................................................................................. 5
JAVA AND PHP CODING STANDARD ................................................................................................... 6
3.1
NAMING JAVA AND PHP CONTRUCTS........................................................................................................ 6
3.1.1
Class names ................................................................................................................................... 6
3.1.2
3.1.3
Method names ................................................................................................................... 6
Java Interfaces names ...................................................................................................... 6
3.1.4
3.1.5
3.1.6
3.1.5
Members and temporary variable names........................................................................................ 6
Constant names ............................................................................................................................... 7
PHP opening tags ........................................................................................................................... 7
PHP closing tagess ......................................................................................................................... 7
3.2
STATEMENTS ........................................................................................................................................... 7
3.2.1
Simple statement ............................................................................................................................. 7
3.2.2
Compound statement....................................................................................................................... 8
3.2.3
Return statement ............................................................................................................................. 8
3.2.4
If else if-else statement .................................................................................................................... 8
3.2.5
Loops statement .............................................................................................................................. 9
3.2.6
Switch statement ............................................................................................................................. 9
3.2.7
Try catch statement ......................................................................................................................... 9
3.3
COMMENTING ........................................................................................................................................ 10
3.3.1
createing PHPdoc and Javadoc comments .......................................Error! Bookmark not defined.
3.3.2
Meaningful comments ......................................................................Error! Bookmark not defined.
3.4
ERROR HANDLING ................................................................................................................................. 10
3.4.1
Never ignore catugh exceptions .......................................................Error! Bookmark not defined.
Page 3
Usman Alam
Coding Policy
Version:
Error! Unknown
document property name.0
Date: 2011-10-08
1. Introduction
1.1 Purpose of this document
The purpose of this document is defining the code standard for Cold Watch project. This
document describes a collection of standards, conventions and guidelines for writing Java and PHP
code that are easy to understand, to maintain for team members and enhance code readability for
examiners.
.
1.2 Document organization
The document is organized as follows:



Section 1, Introduction, describes contents of this guide and main purpose of this
document.
Section 2, Why coding standards are important during project development.
Section 3, Java and PHP coding Standard and conventions.
1.3 Target Audience
The target audiences are Cold Watch teams, steering group and supervisor of the project.
1.4 References
[1] Java and php Coding Standard: www.javaprogrammingworld.com/java-coding-conventions.doc
[2] Java and php Coding Standard:
https://core.forge.funambol.org/files/documents/52/135/file_135.dat/Funambol%20Coding%20Standards.pdf
Page 4
Usman Alam
Coding Policy
Version:
Error! Unknown
document property name.0
Date: 2011-10-08
2. Why Coding Standards are Important
There some reason those describe why it is important
2.1 Code Consistency
Coding standards are important because they lead to greater consistency within code of all
team members. Consistency leads to code that is easier to understand, which in turn results in a code,
which is easier to develop and maintain.
2.2 Avoid Risk
There is a risk involved in such code that is difficult to understand and maintain runs the risk
of being scrapped and rewritten.
2.3 Understandable for others
It is very rare that software original developer/s is maintained for its whole life. If you have
good coding conventions others can understand new code more quickly and thoroughly.
2.4 Product
If you are developing your source code as a product, you need to make sure it is as well
packaged and clean.
Page 5
Usman Alam
Coding Policy
Version:
Error! Unknown
document property name.0
Date: 2011-10-08
3. Java and PHP Coding Standard
3.1 Naming Java and PHP Constructs
This section describes the conventions used for naming classes, methods, member variables
and parameters.
3.1.1 Classes Names



Take the time to create descriptive names that help users determine what the class does.
Names representing types must be nouns and written in mixed case starting with upper case.
Use long names if appropriate and avoid abbreviations.
Cold Watch convention:
class DataCollection {
}
3.1.2 Method Names
The first word in a method name is lowercase. Capitalize the first letter of each successive
word in the method;
Cold Watch convention:
getTemperture(), setCurrentStatus()
3.1.3 Java Interfaces Names
The name of interface should start a prefixed with capital “I”.
Cold Watch convention:
interface IDataCollectioin {
}
interface IGSNSystem{
}
3.1.4 Members and Temporary Variable Names
All instance, class, and class constants are in mixed case with a lowercase first letter. Internal words
start with capital letters. Variable names should not start with underscore. Common names for
temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
Cold Watch convention:
humidity, temperature etc...
Page 6
Usman Alam
Coding Policy
Version:
Error! Unknown
document property name.0
Date: 2011-10-08
3.1.5 Constant names
The names of variables declared class constants should be all uppercase with words
separated by underscores ("_"). Examples are:
static final int MIN_WIDTH = 4;
static final int MAX_WIDTH = 999;
static final int GET_THE_CPU = 1;
Cold Watch convention:
MAX_TEMPERATURE = 50, MIN_HUMIDITY = 30
3.1.6 PHP Opening Tags
Always used PHP <?php full open tags and don’t used short tags like <?. Because maybe your live
web server doesn’t have short tags on. For example
CORRECT:
<?php echo "Hello World!"; ?>
INCORRECT:
<? echo "Hello World!"; ?>
3.1.7 PHP Closing Tags
Closing tags in php are optional to close and it is good practice don't used closing tags because if you
used any white space after closing tag it would case of an error because it wouldn't parse. Thats why it
is good habit to avoid use of closing tags.
INCORRECT:
<?php echo "Hello World!"; ?>
CORRECT:
<?php echo "Hello World!";
3.2
Statements
3.2.1 Simple Statement
Each line should contain at most one statement. For example
Page 7
Usman Alam
Version:
Error! Unknown
document property name.0
Date: 2011-10-08
Coding Policy
argv++;
argc--;
argv++; argc--;
// Correct
// Correct
// AVOID!
3.2.2 Compound Statement
The opening brace should be at the end of the line that begins the compound statement; the
closing brace should begin a line and be indented to the beginning of the compound statement.
Cold Watch convention:
if(flag == 1) {
//do something
}
3.2.3 Return Statement
A return statement with a value should not use parentheses unless they make the return value
more obvious in some way. For example
return;
return myDisk.size();
return (size ? size : defaultSize);
3.2.4 If else if-else Statement
The if-else class of statements should have the following form:
if (condition) {
statements;
}
if (condition) {
statements;
} else {
statements;
}
if (condition) {
statements;
} else if (condition) {
statements;
} else {
statements;
}
Please always close if a brace even there is only one statement in it.
if (condition) //AVOID! THIS OMITS THE BRACES {}!
statement;
Page 8
Usman Alam
Version:
Error! Unknown
document property name.0
Date: 2011-10-08
Coding Policy
3.2.5 Loops Statement
A for statement should have the following form:
for (initialization; condition; update) {
statements;
}
A while statement should have the following form:
while (condition) {
statements;
}
A do-while statement should have the following form:
do {
statements;
} while (condition);
3.2.6 Switch Statement
A switch statement should have the following form:
switch (condition) {
case ABC:
statements;
/* falls through */
case DEF:
statements;
break;
case XYZ:
statements;
break;
default:
statements;
break;
}
3.2.7 Try catch Statement
A try-catch statement should have the following format:
try {
statements;
Page 9
Usman Alam
Version:
Error! Unknown
document property name.0
Date: 2011-10-08
Coding Policy
} catch (ExceptionClass e) {
statements;
}
A try-catch statement may also be followed by finally, which executes regardless of whether
or not the try block has completed successfully.
try {
statements;
} catch (ExceptionClass e) {
statements;
} finally {
statements;
}
3.3
Commenting
3.3.1 Creating PHPdoc and Javadoc Comments
Include comments in all of your Java and php files. It is important for readers for their
understandability. It is provide useful information for documentation, and give helpful clues to both
internal and external people who need to understand what the code is supposed to do you don’t
include a comment. For example:
/**
* This is a comment for my function
* @param pArg1 the first argument
* @return a useless value
* @exception MyException a problem occured while accessing the
data store
*/
Cold Watch convention:
Comments should be written in English.
3.3.2 Meaningful comments
Always try to make sure that your comments are meaningful for others even for you when look at
your after few days and carefull when you copying pasting code. Comments always use // instead of
/* when placed in the code.
This is an example of meaningless comment:
// set the name
profile.setName(name);
// set the login
profile.setAge(age);
// create a new user
profile.createNewUser();
Page 10
Usman Alam
Coding Policy
3.4
Version:
Error! Unknown
document property name.0
Date: 2011-10-08
Error Handling
3.4.1 Never ignore Caught Exceptions
It is needed to design well defined exceptions handling code blocks because it makes program
more robust and help to debug the program. Ignore caught exceptions lead to a system with
unpredictable failures. At least log an error containing the exception message. For example
try {
/* code
risky code
code that depends on the risky code succeeding */
}
catch (ExceptionClassName exceptionObjectName) {
// code using methods from exceptionObjectName
}
Page 11