Why Have Code Conventions:
Code conventions are important to programmers for a number of reasons:
- 80% of the lifetime cost of a piece of software goes to maintenance.
- Hardly any software is maintained for its whole life by the original author.
- Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
- If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
File Organization:
A file consists of sections that should be separated by blank lines and an optional comment identifying each section.
Files longer than 2000 lines are cumbersome and should be avoided.
Beginning Comments:
All source files should begin with a c-style comment that lists the class name (if present), version information, date, and copyright notice:
/* * Classname * * Version information * * Date * * Copyright notice */ Indentation:
Just as in HTML, indenting in PHP makes a script easier to follow. The general rule for indenting goes like this: all statements within control structures (if.else., while, foreach, switch, and so forth) should be indented one unit. The typical "unit" consists of 4 spaces, though some people prefer to use a single tab or an alternate number of spaces.
Line Length: Avoid lines longer than 80 characters, since they're not handled well by many terminals and tools.
Wrapping Lines:
When an expression will not fit on a single line, break it according to these general principles:
- Break after a comma.
- Break before an operator.
- Prefer higher-level breaks to lower-level breaks.
- 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 8 spaces instead.
Here are some examples of breaking method calls:
someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5); var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3)); Following are two examples of breaking an arithmetic expression. The first is preferred, since the break occurs outside the parenthesized expression, which is at a higher level.
longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; // PREFER longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; // AVOID Following are two examples of indenting method declarations. The first is the conventional case. The second would shift the second and third lines to the far right if it used conventional indentation, so instead it indents only 8 spaces.
//CONVENTIONAL INDENTATION someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) { … } //INDENT 8 SPACES TO AVOID VERY DEEP INDENTS private static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) { … } Line wrapping for if statements should generally use the 8-space rule, since conventional (4 space) indentation makes seeing the body difficult. For example:
//DON'T USE THIS INDENTATION if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { //BAD WRAPS doSomethingAboutIt(); //MAKE THIS LINE EASY TO MISS } //USE THIS INDENTATION INSTEAD if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); } //OR USE THIS if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); } Here are three acceptable ways to format ternary expressions:
alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma; Comment Formats:
Single-Line Comments:
Short comments can appear on a single line indented to the level of the code that follows. If a comment can't be written in a single line, it should follow the block comment format. A single-line comment should be preceded by a blank line. Here's an example of a single-line comment
if (condition) { /* Handle the condition. */ … }
Trailing Comments:
Very short comments can appear on the same line as the code they describe, but should be shifted far enough to separate them from the statements. If more than one short comment appears in a chunk of code, they should all be indented to the same tab setting. Here's an example of a trailing comment:
if (a == 2) { return TRUE; /* special case */ } else { return isPrime(a); /* works only for odd a */ } End-Of-Line Comments:
The // comment delimiter can comment out a complete line or only a partial line. It shouldn't be used on consecutive multiple lines for text comments; however, it can be used in consecutive multiple lines for commenting out sections of code. Examples of all three styles follow:
if (foo > 1) { // Do a double-flip. … } else { return false; // Explain why here. } //if (bar > 1) { // // // Do a triple-flip. // … //} //else { // return false; //} Declarations:
Number per Line:
One declaration per line is recommended since it encourages commenting. In other words,
int level; // indentation level
int size; // size of table int level, size;
Do not put different types on the same line. Example:
int foo, fooarray[]; //WRONG!
Note: The examples above use one space between the type and the identifier. Another acceptable alternative is to use tabs, e.g.:
int level; // indentation level
int size; // size of table
Object currentEntry; // currently selected table entr
Initialization:
Try to initialize local variables where they're declared. The only reason not to initialize a variable where it's declared is if the initial value depends on some computation occurring first.
Placement:
Put declarations only at the beginning of blocks. (A block is any code surrounded by curly braces "{" and "}".) Don't wait to declare variables until their first use; it can confuse the unwary programmer and hamper code portability within the scope.
void myMethod() { int int1 = 0; // beginning of method block
if (condition) { int int2 = 0; // beginning of "if" block
… } }
The one exception to the rule is indexes of for loops, which can be declared in the for statement:
for (int i = 0; i < maxLoops; i++) { ... } Avoid local declarations that hide declarations at higher levels. For example, do not declare the same variable name in an inner block:
int count;
...
myMethod() { if (condition) { int count = 0; // AVOID!
… } … }
Class and Interface Declarations:
When coding classes and interfaces, the following formatting rules should be followed:
- No space between a method name and the parenthesis "(" starting its parameter list
- Open brace "{" appears at the end of the same line as the declaration statement
- Closing brace "}" starts a line by itself indented to match its corresponding opening statement, except when it is a null statement the "}" should appear immediately after the "{"
class Sample extends Object { int ivar1; int ivar2; Sample(int i, int j) { ivar1 = i; ivar2 = j; } int emptyMethod() {} … }
Methods are separated by a blank line
Statements:
Simple Statements:
Each line should contain at most one statement. Example:
argv++; // Correct argc--; // Correct
argv++; argc--; // AVOID! Compound Statements:
Compound statements are statements that contain lists of statements enclosed in braces "{ statements }". See the following sections for examples.
- The enclosed statements should be indented one more level than the 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.
- Braces are used around all statements, even single statements, when they are part of a control structure, such as a if-else or for statement. This makes it easier to add statements without accidentally introducing bugs due to forgetting to add braces.
Return Statements:
A return statement with a value should not use parentheses unless they make the return value more obvious in some way. Example:
return;
return myDisk.size();
return (size ? size : defaultSize);
If, if-else, if else-if else Statements:
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;
}
Note: if statements always use braces {}. Avoid the following error-prone form:
if (condition) //AVOID! THIS OMITS THE BRACES {}! statement;
For Statements:
A for statement should have the following form:
for (initialization; condition; update) {
statements;
}
An empty for statement (one in which all the work is done in the initialization, condition, and update clauses) should have the following form:
for (initialization; condition; update);
When using the comma operator in the initialization or update clause of a for statement, avoid the complexity of using more than three variables. If needed, use separate statements before the for loop (for the initialization clause) or at the end of the loop (for the update clause).
While Statements:
A while statement should have the following form:
while (condition) { statements;
}
An empty while statement should have the following form:
while (condition); do-while Statements:
A do-while statement should have the following form:
do { statements;
} while (condition); switch Statements:
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; }
Every time a case falls through (doesn't include a break statement), add a comment where the break statement would normally be. This is shown in the preceding code example with the /* falls through */ comment.
Every switch statement should include a default case. The break in the default case is redundant, but it prevents a fall-through error if later another case is added.
try-catch Statements:
A try-catch statement should have the following format:
try { statements;
} 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;
}
White Space:
Blank Lines
Blank lines improve readability by setting off sections of code that are logically related.
Two blank lines should always be used in the following circumstances:
One blank line should always be used in the following circumstances:
- Between methods
- Between the local variables in a method and its first statement
- Before a block single-line comment
- Between logical sections inside a method to improve readability
Blank Spaces
Blank spaces should be used in the following circumstances:
while (true) { … } Note that a blank space should not be used between a method name and its opening parenthesis. This helps to distinguish keywords from method calls.
- A blank space should appear after commas in argument lists.
- All binary operators except. should be separated from their operands by spaces. Blank spaces should never separate unary operators such as unary minus, increment ("++"), and decrement ("�") from their operands. Example:
a += c + d; a = (a + b) / (c * d); while (d++ = s++) { n++; } printSize("size is " + foo + "\n"); for (expr1; expr2; expr3) myMethod((byte) aNum, (Object) x); myMethod((int) (cp + 5), ((int) (i + 3)) + 1); Naming Conventions
Classes
Class names should be nouns, in mixed case with the first letter of each internal word capitalized. Try to keep your class names simple and descriptive. Use whole words-avoid acronyms and abbreviations (unless the abbreviation is much more widely used than the long form, such as URL or HTML).
Interfaces
Interface names should be capitalized like class names.
Methods
Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized.
Variables
Except for variables, 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 _ or dollar sign $ characters, even though both are allowed.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
Constants
The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.) Numerical constants (literals) should not be coded directly, except for -1, 0, and 1, which can appear in a for loop as counter values.
Variable Assignments
Avoid assigning several variables to the same value in a single statement. It is hard to read. Example:
fooBar.fChar = barFoo.lchar = 'c'; // AVOID!
Do not use the assignment operator in a place where it can be easily confused with the equality operator. Example:
if (c++ = d++) { // AVOID! …
}
if ((c++ = d++) != 0) { … }
Do not use embedded assignments in an attempt to improve run-time performance. This is the job of the compiler. Example:
d = (a = b + c) + r; // AVOID! a = b + c;
d = a + r;
Miscellaneous Practices:
Parentheses
It is generally a good idea to use parentheses liberally in expressions involving mixed operators to avoid operator precedence problems. Even if the operator precedence seems clear to you, it might not be to others-you shouldn't assume that other programmers know precedence as well as you do.
if (a == b && c == d) // AVOID! if ((a == b) && (c == d)) // RIGHT
Returning Values
Try to make the structure of your program match the intent. Example:
if (booleanExpression) { return true; } else { return false; }
return booleanExpression; if (condition) { return x; }
return y;
return (condition ? x : y);
Expressions before `?' in the Conditional Operator
If an expression containing a binary operator appears before the ? in the ternary ?: operator, it should be parenthesized. Example:
(x >= 0) ? x : -x;
Special Comments
Use XXX in a comment to flag something that is bogus but works. Use FIXME to flag something that is bogus and broken.
Modularize Scripts:
- When the term modularization is used in the context of programming, it refers to the process of breaking a large application up into separate parts, or "modules," that perform specific jobs.
- When you begin writing a script, you will find that certain blocks of code are frequently re-used. Common tasks like connecting to databases, validating user input, and checking a user's login information can occur multiple times throughout the scripts of a complete application. Initially, the inclination might be to copy and paste your code block to wherever it happens to be needed. But, this gets messy; if you need to alter the code block in one script, you're condemned to updating it everywhere else it occurs.
- Create a separate file for the functions, methods which we use frequently in the project. These files we call as global files. These "global" files can be shared among all the other scripts in the application by including them using include () or require () functions.
Avoid Double Quotes around Strings that Contain HTML:
To avoid variable concatenation, many people get in the habit of using double quotes for strings looking like this
$var = "<table width=\"0\" border=\"0\" cellpadding=\"0\" width=\"100%\" cellspacing=\"0\"><tr><td style=\"font-family:Verdana;\"><a href=\"$url\">$link</a></td></tr></table>";
Strings like this should be re-written as:
$var = '<table width="0″ border="0″ cellpadding="0″ width="100%" cellspacing="0″><tr><td style="font-family:Verdana;"><a href="'.$url.'">'.$link.'</a></td></tr></table>';
By using single quotes, the need to escape every interior double quote is removed. There is a very small performance gain that can add up over the course of a single script (especially in cases where there are no variables within the string), because the processor does not need to search the string for any variables.
Use Logical and Consistent Naming Conventions:
We have to use proper naming conventions for all variables. Names for elements should be short, but descriptive of the task they perform or the information they hold. If you decide to capitalize function names, maintain the same format for all of them. If you are using any user defined functions then specify the purpose of that particular function at function definition as comments.
--
Thanks & Regards,
B.Chandra Shekhar.
Software Engineer,
Jiva Infotech Pvt Ltd.
No comments:
Post a Comment