Ministry of education and training fpt university

IV. Coding convention

This document describes rules and recommendations for developing applications and class libraries using the Java and Language. The goal is to define guidelines to enforce consistent style and formatting and help developers avoid common pitfalls and mistakes. This document is a collection of standards, conventions and guidelines for writing Java and C# code that is easy to understand, to maintain, and to enhance.

This section lists commonly used file suffixes and names.

Java Software uses the following file suffixes:

File Type	Suffix
Java source	.java
Java bytecode	.class

Frequently used file names include:

File Name	Use
README	The preferred name for the file that summarizes the contents of a particular directory.

Four spaces should be used as the unit of indentation.

Tab characters should be avoided because different editors interpret tabs differently.

Continuation indent should be configured to 8 spaces (two normal indentation levels).

Open curly brace “{” of class/method declarations and other code blocks should be at “END OF LINE” of the first statement of code block.

Avoid lines longer than 80 or 120 characters, since they're not handled well by many terminals and tools.

Java programs can have two kinds of comments: implementation comments and documentation comments. Implementation comments are those found in C++, which are delimited by /*...*/, and //. Documentation comments (known as "doc comments") are Java-only, and are delimited by /**...*/. Doc comments can be extracted to HTML files using the javadoc tool.

Implementation comments are mean for commenting out code or for comments about the particular implementation. Doc comments are meant to describe the specification of the code, from an implementation-free perspective to be read by developers who might not necessarily have the source code at hand.

Comments should be used to give overviews of code and provide additional information that is not readily available in the code itself. Comments should contain only information that is relevant to reading and understanding the program. For example, information about how the corresponding package is built or in what directory it resides should not be included as a comment.

Programs can have four styles of implementation comments: block, single-line, trailing, and end-of-line.

Block comments are used to provide descriptions of files, methods, data structures and algorithms. Block comments may be used at the beginning of each file and before each method. They can also be used in other places, such as within methods. Block comments inside a function or method should be indented to the same level as the code they describe.

A block comment should be preceded by a blank line to set it apart from the rest of the code.

/*

*/

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 in Java

if (condition) {

// Handle the condition.

...

}

2.3.1.3 Trailing Comments

Here's an example of a trailing comment in Java code:

if (a == 2) {

return TRUE; // special case

} else {

return isPrime(a); // works only for odd a

}

2.3.1.4 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 {

}

2.4. Declarations

One declaration per line is recommended since it encourages commenting. In other words,

int level; // indentation level

int size; // size of table

is preferred over

int level, size;

Do not put different types on the same line. Example:

int foo, fooarray[]; //WRONG!

int level; // indentation level

int size; // size of table

Object currentEntry; // currently selected table entry

Though Java supports two styles of array declarations, we should only follow one as following:

int anIntArray[]; // AVOID

int[] anIntArray; // RECOMMENDED

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.

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

...

}

}

for (int i = 0; i < maxLoops; i++) {

tempString = ...;

...

Local variables used inside loops should be declared outside and right before the loop statement, as shown in above example.

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() {

int count = 0; // AVOID!

...

}

...

When coding Java classes and interfaces, the following formatting rules should be followed:

Opening bracket "{" always appears at end of line.

Closing bracket "}" should appear on a new line.

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

Each line should contain at most one statement. Example:

argv++; // Correct

argc--; // Correct

argv++; argc--; // AVOID!

2.5.2 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.

2.5.3 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);

2.5.4 if, if-else, if else-if else Statements

The if-else class of statements should have the following form:

if (condition) {

statements;

}
if (condition) {

} else {

}
if (condition) {

} else if (condition) {

} else {

}

2.5.5 for Statements

A for statement should have the following form:

for (initialization; condition; update) {

}

An empty for statement (one in which all the work is done in the initialization, condition, and update clauses) should have the following form:

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).

A while statement should have the following form:

while (condition) {

statements;

}

An empty while statement should have the following form:

A do-while statement should have the following form:

do {

statements;

} while (condition);

A switch statement should have the following form:

switch (condition) {

case ABC:

/* falls through */

case DEF:

statements;

break;

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.

2.5.9 Try-catch Statements

A try-catch statement should have the following format:

try {

statements;

} catch (ExceptionClass e) {

}

A try-catch statement may also be followed by finally, which executes regardless of whether or not the try block has completed successfully.

} catch (ExceptionClass e) {

} finally {

}

Blank spaces should be used in the following circumstances:

• 
  A keyword followed by a parenthesis should be separated by a space
  

• 
  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 = (a + b) / (c * d);

while (d++ = s++) {

n++;

printSize("size is " + foo + "\n");

• 
  The expressions in a for statement should be separated by blank spaces. Example:
  

• 
  Casts should be followed by a blank space. Examples:
  

myMethod((int) (cp + 5), ((int) (i + 3)) + 1);

Naming conventions make programs more understandable by making them easier to read.

They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code.

2.7.1 General Rules

This section outlines the rules to be followed while naming Source File / variable / control / method.

1. 
   Programmer defined names should be functionally meaningful, and should indicate the purpose of the file / variable / control / method in question.
   
2. 
   Use terminology applicable to the domain.
   

Many developers will make the mistake of creating generic terms for concepts when perfectly good terms already exist in the industry/domain.

3. 
   Identifiers must be as short as possible without obscuring their meaning, preferably 20 characters
   

iv. Avoid names that are similar or differ only in case.

For example, the variable names persistentObject and persistentObjects should not be used together, nor should anSqlDatabase and anSQLDatabase

4. 
   Avoid cryptic names, even in case of scratch pad variables or counters.
   

5. 
   Abbreviations in names should be avoided.
   

computeAverage(); // NOT: compAvg();

generateHTML(); // NOT: generateHypertextMarkupLanguage();

Unambiguous abbreviations should be used wherever possible. For example, use custName instead of customerName. Capitalize the whole abbreviation.

6. 
   The method name should not contain any special characters other than underscore.
   

Each class/interface name must start with uppercase and respect the general rules of above naming convention , e.g. class CustomerBean.

• 
  Exception classes should be suffixed with Exception, e.g. LMSFunctionalException.
  
• 
  Interfaces having no method should be prefixed with I, e.g. IConstants.
  
• 
  Abstract classes should be prefixed with Abstract, e.g. abstract class AbstractBean.
  
• 
  Implementation classes should be suffixed with Impl, e.g. class CustomerBOImpl implements CustomerBO.
  

• 
  Each variable name must start with lowercase and respect the general rules of naming convention , e.g. custName.
  
• 
  List variables (of type Collection/List) should be suffixed with List, e.g. Collection custList.
  
• 
  Set variables (of type Set/HashSet) should be suffixed with Set, e.g. Set custSet = new HashSet();
  
• 
  Map variables (of type Map/HashMap/TreeMap) should be suffixed with Map, e.g. Map custMap = new TreeMap();
  
• 
  Array variables can be suffixed with Array, e.g. int[] custIDArray;
  
• 
  The use of ID or Id should be consistent throughout an application.
  

The following guidelines should be followed while naming constants:

• 
  Respect the general rules of naming convention .
  
• 
  All constants to be named in uppercase letters, with underscore between words.
  
• 
  All constants must be declared as static final.
  

The following guidelines to be followed while naming methods in class files:

• 
  Respect the general rules of naming convention
  
• 
  Method name must start with lowercase letter.
  
• 
  Usually use “active verb” as the first word of method name. Here are some common verbs:
  

isActive, hasAddresses

findCustomers, searchCustomers

computeSalary, calculateSalary

initializeParameters, initParameters

addCustomer, removeCustomer

insertCustomer, deleteCustomer

updateCustomer, modifyCustomer, amendCustomer

openConnection, closeConnection, saveFile

createBuffer, destroyBuffer

startProcess, stopProcess

• 
  Verbs should be used by pairs and should be used consistently throughout an application.
  

• 
  Some special methods not starting with verbs:
  

Conversion methods: toString(), toLongPhoneNumber(), toXXX()

3. C# language

3.1 Description

This section contains tables describing a high-level summary of the major standards covered in this document. These tables are not comprehensive, but give a quick glance at commonly referenced elements.

“c” = camel Case

“P” = Pascal Case

“_” = Prefix with _Underscore