Know more about coding standards and comments
• What is the need of coding standards and comments?
Coding standards and comments are for the programmer’s ease of understanding the program. They improve the readability of the software.
Another good reason for the need of coding standards and appropriate comments in the program is that, more than 75% of the lifetime cost of a piece of software goes to maintenance and any software is hardly maintained by its original author for its whole life. In this case, appropriate comments in the program will help the new engineers understand the logic of the original author of the program, quickly and thoroughly and take the project further. It will also be helpful to the author of the program in recollecting the logic he has used in it, in a later point of time.
• Do the comments in the program get compiled into the final executable file?
No, all the comments and blank spaces put into program as part of indentation are filtered out at the time of compiling.
Coding Standards
1. Packages
• Package names should help in understanding the program and functions of the files in it.
• Package name should have a proper hierarchy and should be in all-lowercase.
• Files of similar functionality should be put into same package.
• Use different sub packages if needed, instead of putting all your source files into one package.
• Prefix of a package name should always be one of the top-level domain names: com, edu, gov, mil, org or English two-letter codes of countries according to ISO Standard 3166, 1981 and rest of the package name can be according to the internal naming convention of the organization, it can specify division, department, working-unit, etc.
• Eg:
com.infosys.tvm.ped.apple
2. Files
• Files can have maximum of 2000 lines of code.
• Separate different sections of your file with a blank line.
• Write an optional comment for each section for identifying it.
2.1. Source files
• Source files can contain a single public class or interface.
• Private classes and interfaces associated with public classes can be put in the same source file as the public class.
• Public class or interface should be in the beginning of the source file.
• Source file structure:
o Source file should start with a comment of format given below:
/*
*Class name:
*
*Version information:
*
*Date:
*
*Copyright notice:
*/
Eg:
/*
*
*HelloWorld.java 1.09 11th Oct 1989
*
*/
o Package and import statements:
package com.infosys.ped.apple;
import java.util.*;
o Class and Interface declarations.
2.1.1. Classes
• Class names should be nouns, in mixed case with the first letter of every word capitalized.
Eg:
class Infosys;
class InfosysEmployee
• Class names should be simple and descriptive.
• Use only widely used abbreviations and acronyms in class names; rest of the words should be as whole-words.
• Comment for the class:
/*
*Class description:
*
*Version:
*
*Author:
*/
2.1.2. Interfaces
• Interface name should follow all the standards as class names.
• Eg:
interface Car;
interface InfosysClient;
2.1.3. Methods
• Method names should be verbs in mixed cases, with starting letter lowercase and first letter of all internal words capitalized.
Eg:
erase();
getName();
averageWorkHours();
•
• Methods should be prefixed with a comment, describing the purpose of it, its argument list and its return value.
• Separate methods with a blank line.
• There should not be space between method name and parenthesis and opening curly braces need to be in the same line as method header; use a new line for closing curly brace.
Eg:
void sayHelloToWorld() {
String stringToPrint = “Hello World… “;
. . .
if (conditional_expression) {
System.out.println();
. . .
}
. . .
}
2.1.4. Variables
• Variable names should be in mixed case with starting letter lowercase and first letter of all internal words capitalized.
• Variable names should be short and meaningful. It should indicate the intent of its use.
• Variable names should not start with underscore (“_”) or dollar sign (“$”) even though it’s possible.
• Do not wait to declare variables until their first use.
• Variables of one character length should be avoided except for temporary variables. Common practice is to use i, j, k, m and n for integers and c, d and e for characters.
Eg:
int i;
char c;
float mySalary;
• Prefer tabs to space between data type and variables. This will make your program look aligned.
Eg:
String unitName; //preferred
int noOfEmployees; //preferred
String unitName; //not a good practice
int noOfEmployees; //not a good practice
• Using a new line for every declaration and commenting it is a good practice.
Eg:
int myAge; //present age of the user
float mySalary //annual income of the user
• Avoid declaration different types in same line.
Eg:
String name, nicknames[5]; //Wrong
2.1.5. Constants
• Constant variable’s name should be fully capitalized with words separated by underscore (“_”)
• Eg:
static final int MAX_AGE_LIMIT=65;
3. Indentation
• Avoid lines longer than 80 characters. Programs should be readable without scrolling horizontally.
• Break expressions, either after a comma or before an operator, which does not fit in a single line. Indent it properly to avoid confusion.
• Eg:
var = myFunction1( myParameter1, myParameter2, myParameter3,
myParameter4, myParameter5);
float sum1 = someNumber1 + someNumber2 + someNumber3
+ (someNumber4 – someNumber5);
Good programming practices
• Use library utilities wherever possible, instead of coding your own logic. Library utilities are optimized for speed and performance and use of these will make the program perform better.
• var1++; var2++; //Wrong practice
var1++; //Correct
var2++ //Correct
• Always use curly braces with “ if ” conditions and “ for ” statements even if there is only one statement inside the block.
• Separate expressions in a “ for ” statement with a blank space.
Eg:
for (expression1; expression2; expression3)
• Do not declare any of the class or instance variables as public unless its unavoidable.
• Avoid using of the instance variables to access class variables.
• zoo.var1 = boo.var2 = 2; //Wrong; makes the program complicated to read
• if (c==d && d==e) //Wrong practice
if ((c==d) && (d==e)) //Correct
• i == 1 ? 100 : 0; //Wrong practice
(i==1) ? 100 : 0; //Correct
References
http://www.oracle.com/technetwork/java/codeconvtoc-136057.html
WikiSree 