Coding Standards in Java
So today we are talking about coding standards in java and why following them is considered to be a good practice.
Programming is a way to communicate with computers by giving instructions to them to perform a particular task. We are writing codes to communicate not only with machines but also with other developers.
The coding guidelines are important because most of the software cost goes towards maintenance. And also, the software is not always developed by a single developer. Therefore, maintaining a convention for writing software increases the readability of the program. So we are talking about some of the coding standards.
A. Naming Conventions:
Naming conventions make programs more understandable by making them easier to read. They can also give information about the function. Giving the proper name of constant, package, or class help in understanding the code.
- Classes: Class names should be nouns, in mixed cases with the first letter of each internal word capitalized and class names should be simple and descriptive. Example: class Client, class RequestProcess, etc.
- Interfaces: Interface names should be capitalized like class names. Example: interface RasterDelegate; interface Storing, etc.
- Methods: Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized. Example: run(), runFast(), getBackground(), etc.
- Variables: Variables in mixed case with a lowercase first letter. Internal words start with capital letters. Variable names should be short yet meaningful. Example: float myWidth , myHeight.
- Constants: The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores. Example: int MIN_WIDTH = 4; int MAX_WIDTH = 999, etc.
B. Indentation:
Four spaces should be used as the unit of indentation. The exact construction of the indentation (spaces vs. tabs) is unspecified. Tabs must be set exactly every 8 spaces (not 4).
C. Comments:
Java programs can have two kinds of comments: implementation comments and documentation comments. Implementation comments are delimited by /*…*/, and //. Documentation comments (known as “doc comments”) are declared by /**…*/. 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. With the bits of help of this other programmers should understand what is the actual work of the following code snippet.
1.Implementation Comment Formats: Programs can have four styles of implementation comments: block comments, single-line comments, trailing comments, and end-of-line comments.
a. Block Comments: Block comments are used to provide descriptions of files, methods, data structures, and algorithms. Block comments should be used at the beginning of each file and before each method. They can also be used in other places, such as within methods.
/*
*Here is a block comment.
*/
b.Single-Line Comments: Short comments can appear on a single line indented to the level of the code that follows.
if (condition) {
/* Handle the condition. */
…
}
c.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. Avoid the assembly language style of commenting every line of executable code with a trailing comment.
if (a == 2) {
return TRUE; /* special case */
} else {
return isprime(a); /* works only for odd a */
}
d.End-Of-Line Comments: The // comment delimiter begins a comment that continues to the newline. It 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;
2.Documentation Comments: Documentation comments describe Java classes, interfaces, constructors, methods, and fields. Each doc comment is set inside the comment delimiters /**…*/, with one comment per API. This comment should appear just before the declaration:
/**
*The Example class provides …
*/
class Example { …
D. Declarations:
1.Number Per Line: One declaration per line is recommended since it encourages commenting. In other words,
int level; // indentation level
int size; // size of the table
is preferred over
int level, size;
In absolutely no case variables and functions be declared on the same line. It is not preferable and also wrong.
Example: long dbaddr, getDbaddr(); // WRONG!
Do not put different types on the same line.
Example: int foo, fooarray[]; //WRONG!
2. Placement: Put declarations only at the beginning of blocks.
void MyMethod() { int int1; // beginning of method block
if (condition) {
int int2; // beginning of “if” block
…
}
}
3. 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.
E. Statements:
1.Simple Statements: Each line should contain at most one statement. Example: argv++; argc — ; // AVOID!
Example: argv++;
argc — ; //RIGHT
Do not use the comma operator to group multiple statements unless it is for an obvious reason.
Example: if (err) {
Format.print(System.out, “error”), exit(1); // WRONG!
}
2. Compound Statements: Compound statements are statements that contain lists of statements enclosed in braces “{ statements }”.
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);
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) {
statements;
} else {
statements;
}
if (condition) {
statements;
} else if (condition) {
statements;
} else if (condition) {
statements;
}
5. 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);
6. while Statements: A while statement should have the following form: while (condition) {
statements;
}
An empty while statement should have the following form:
while (condition);
7. do-while Statements: A do-while statement should have the following form:
do {
statements;
} while (condition);
8. switch Statements: A switch statement should have the following form: switch (condition) {
case ABC:
statements;
break;
case DEF:
statements;
break;
case XYZ:
statements;
break;
default:
statements;
break;
}
9. try-catch Statements: A try-catch statement should have the following format:
try {
statements;
} catch (ExceptionClass e) {
statements;
}
F. Miscellaneous Practices:
- Parentheses: It is generally a good idea to use parentheses liberally in expressions involving mixed operators to avoid operator precedence problems.
if (a == b && c == d) // AVOID!
if ((a == b) && (c == d)) // RIGHT
2. Returning Values: Try to make the structure of your program match the intent. Example:
if (booleanExpression) {
return TRUE;
} else {
return FALSE;
}
should instead be written as
return (condition ? x : y);
Conclusion
Nowadays many IDEs such as IntelliJ or Eclipse already provide code formating options using which most of the coding conventions can be followed. But we still need to add comments as they are not yet smart enough to also do it.