The intent
of this document is to create a guide for software source code quality based on Java Standard. The guidelines appearing herein apply to anyone who
creates, modifies or read software source code for Java.
This
document is not a description of a complete software process. A particular
group will need to develop their own methodologies and procedures for the
specification, design, implementation, testing and deployment of their software
systems. This document is simply a set of rules to follow during the
implantation phase that will help produce a high quality result.
You can hope
to achieve three goals by requiring a consistent source code style.
- ·
Improving
the productivity of existing programmers.
- ·
Allow
new programmers to become comfortable with existing source code in less time
than would otherwise be necessary.
- ·
Allow
existing programmers to move around to different projects easily without having
to adjust to the programming style in use by other groups.
Standardizing
the "look and feel" of the source code will reduce the time to
market, it will reduce the time spent correcting problems in the product line,
and it will give engineers the flexibility to jump on and off projects without
a large learning curve. This means that you will be able to spend less time on legacy
products and jump into the more interesting task of designing and implementing
future products.
This
Document delves into some fundamental java programming techniques and provides
a rich collection of coding practices to be followed by JAVA/J2EE based
application development teams for Java.
This
document is written for Java software developers to help them:
- ·
Write
java code that is easy to maintain and enhance
- ·
Increase
their productivity
3.1.1.1.
Naming packages
The rules
associated with the naming of packages as follows:
Unless required
otherwise, a package name should include the organization’s domain name, with
the top level domain type in lower case ASCII letters i.e. com.<Name of company> followed by project name and sub
project name as specified in ISO Standard 3166, 1981.
Eg:- com.<companyname>.<modulename>.<other>
Subsequent
components of the package name vary according to requirements.
Package
names should preferably be singular.
3.1.1.2.
Documenting a Package
There should
be one or more external documents in html format with the package name that
describe the purpose of the packages documenting the rationale for the package,
the list of classes and interfaces in the package with a brief description of
each so that other developers know what the package contains.
Naming Classes:
Class names
should be simple full English descriptor nouns, in mixed case starting with the
first letter capitalized and the first letter of each internal word also
capitalized. Whole words should be used instead of acronyms and abbreviations
unless the abbreviation is more widely used than the long form, such as URL or
HTML.
Class Visibility:
Package or
default visibility may be used for classes internal to a component while public
visibility may be used for other components. However, for a good design, the
rule is to be as restrictive as possible when setting the visibility. The
reason why the class is public should be documented. Each class should have an
appropriate constructor.
Documenting a Class:
The
documentation comments for a class start with the header for class with
filename, version, copyright and related information. The documentation
comments should precede the definition of a class and should contain necessary
information about the purpose of the class, details of any known bugs, examples
etc. as illustrated in. The development/maintenance history of the class should
be entered as comments in the configuration management tool at the time of
baselining the source code and in the file header as well.
The Java
convention is to name interfaces using mixed case with the first letter of each
word capitalized like classes. The preferred convention for the name of an
interface is to use a descriptive adjective, such as Runnable or Clone able.
Interfaces should be documented specifying the purpose of the interface and how
it should and shouldn’t be used. Method declarations in interfaces should
explicitly declare the methods as public for clarity.
Naming Methods:
Methods
should be named using a full English description, using mixed case with the
first letter of any non-initial word capitalized. It is also common practice
for the first word of a method name to be a strong, active verb. e.g. getValue(), printData(), save()
,delete(). This convention results in methods whose purpose can often be
determined just by looking at its name. It is recommended that accessor methods
be used to improve the maintainability of classes.
Getters:
Getters are
methods that return the value of a field. The word ‘get’ should be prefixed to
the name of the field, unless it is a boolean field where ‘is’ should be
prefixed to the name of the field. e.g. getTotalSales(), isPersistent().
Alternately the prefix ‘has’ or ‘can’ instead of ‘is’ for boolean getters may
be used. For example, getter names such as hasDependents()
and canPrint() can be created. Getters should always be made protected, so
that only subclasses can access the fields except when an ‘outside class’ needs
to access the field when the getter method may be made public and the setter
protected.
Setters:
Setters,
also known as mutators, are methods that modify the values of a field. The word
‘set’ should be prefixed to the name of the field for such methods type.
Example: setTotalSales(), setPersistent(boolean isPersistent)
Getters for constants:
Constant
values may need to be changed over a period of time. Therefore constants should
be implemented as getter methods. By using accessors for constants there is
only one source to retrieve the value. This increases the maintainability of
system.
Accessors for collections:
The main
purpose of accessors is to encapsulate the access to fields. Collections, such
as arrays and vectors need to have getter and setter method and as it is
possible to add and remove to and from collections, accessor methods need to be
included to do so. The advantage of this approach is that the collection is
fully encapsulated, allowing changes later like replacing it with another
structure, like a linked list.
Examples:
getOrderItems(), setOrderItems(), insertOrderItem(), deleteOrderItem(),
newOrderItem()
Method Visibility:
For a good
design, the rule is to be as restrictive as possible when setting the
visibility of a method. If a method doesn’t have to be private then it should
have default access modifier, if it doesn’t have to be default then it should
be made protected and if it doesn’t have to protect only then it should be made
public. Wherever a method is made more visible it should be documented why.
Access
modifier for methods should be explicitly mentioned in cases like interfaces
where the default permissible access modifier is public.
Standards for Parameters (Arguments) to Methods
:
Parameters
should be named following the same conventions as for local variables.
Parameters to a method are documented in the header documentation for the
method using the javadoc@param tag.
However:
- ·
Cascading
method calls like method1().method2() should be avoided.
- ·
Overloading
methods on argument type should be avoided.
- ·
It
should be declared when a class or method is thread-safe.
- ·
Synchronized
methods should be preferred over synchronized blocks.
- ·
The
fact that a method invokes wait should always be documented.
- ·
Abstract
methods should be preferred in base classes over those with default implementations.
- ·
All
possible overflow or underflow conditions should be checked for a computation.
There should
be no space between a method/constructor name and the parenthesis but there
should be a blank space after commas in argument lists.
Naming Variables:
Use a full
English descriptor for variable names to make it obvious what the field
represents. Fields, that are collections, such as arrays or vectors, should be
given names that are plural to indicate that they represent multiple values.
Variable names should not start with an underscore _ or dollar sign $
characters and should be short and meaningful. The choice of a variable name
should be mnemonic i.e., designed to indicate to the casual observer the intent
of its use. Single character variable names should be avoided except for
temporary “throwaway” variables.
Naming Components:
For names of
components, full English descriptor should be used, post fixed by the Component
type. This makes it easy to identify the purpose of the component as well as
its type, making it easier to find each component in a list. Therefore names
like NewHelpMenuItem, CloseButton should be preferred over Button1, Button2, etc.
Naming Constants:
Constants,
whose values that do not change, are typically implemented as static final
fields of classes. They should be represented with full English words, all in
uppercase, with underscores between the words like FINAL_VALUE.
Naming Collections:
A
collection, such as an array or a vector, should be given a pluralized name
representing the types of objects stored by the array. The name should be a
full English descriptor with the first letter of all non-initial words
capitalized like customers, orderItems, aliases.
Naming Local Variables:
In general,
local variables are named following the same conventions as used for fields, in
other words use of full English descriptors with the first letter of any
non-initial word in uppercase. For the sake of convenience, however, this
naming convention is relaxed for several specific types of local variable like
Streams, Loop counters, Exceptions. Name hiding or data hiding refers to the
practice of naming a local variable, argument, or methods the same or similar
as that of another one of greater scope in same or super class. This may lead
to confusion and should be avoided.
Naming Streams:
When there
is a single input and/or output stream being opened, used, and then closed
within a method the common convention is to use ‘in’ and ‘out’ for the names of
these streams, respectively.
Naming Loop Counters:
Loop
counters are a very common use for local variables therefore the use of i, j,
or k, is acceptable for loop counters where they are obvious. However, if these
names are used for loop counters, they should be used consistently. For complex
nested loops the counters should be given full meaningful English descriptors.
Each method
should declare the javadoc tags exactly in the sequence as given below. Each line
item begins with an asterisk. All subsequent lines in multiline component are
to be indented so that they line up vertically with the previous line. For
reference, the javadoc tags are explained in detail in Annexure.
Example:
/**
* Description:
* @param <Mandatory Tag> for description of
each parameter
* @return <Mandatory Tag> except for
constructor and void>
* @exception <Optional Tag>
* @see <Optional Tag>
* @since <Optional Tag>
* @deprecated <Optional Tag>
*/
Efficient String Concatenations
For making a
long string by adding different small strings always use append method of java.lang.StringBuffer
and never use ordinary ‘+’ operator for adding up strings.
Optimal use of Garbage collection
For easing
out the work of java Garbage Collector always set all referenced variables used
to ‘null’ explicitly thus de-referencing the object which is no more required
by the application and allowing Garbage Collector to swap away that variable
thus realizing memory.
Use variables in any code optimally
Try to make
minimum number of variables in JSP/Java class and try to use already made
variables in different algorithms shared in same JSP/Java class by setting
already populated variable to ‘null’ and then again populating that variable
with new value and then reusing them.
Try to reduce the number of hits to
database
Number of
hits to the database should be reduced to minimum by getting data in a well
arranged pattern in minimum number of hits by making the best use of joins in
the database query itself rather than getting dispersed data in more number of
hits.
Heavy Object should not be stored in
sessions
Storing
heavy objects in the Session can lead to slowing of the running of the JSP page
so such case should be avoided.
Always use database connection pooling
Always use
javax.sql.DataSource which is obtained through a JNDI naming lookup. Avoid the
overhead of acquiring a javax.sql.DataSource for each SQL access. This is an
expensive operation that will severely impact the performance and scalability
of the application.
Release database resources when done
Failing to
close and release JDBC connections can cause other users to experience long
waits for connections. Although a JDBC connection that is left unclosed will be
reaped and returned by Application Server after a timeout period, others may
have to wait for this to occur. Close JDBC statements when you are through with
them. JDBC ResultSets can be explicitly closed as well. If not explicitly
closed, ResultsSets are released when their associated statements are closed.
Ensure that your code is structured to close and release JDBC resources in all
cases, even in exception and error conditions.
Minimum use of System.out.println
Because it
seems harmless, this commonly used application development legacy is overlooked
for the performance problem it really is. Because System.out.println statements
and similar constructs synchronize processing for the duration of disk I/O,they
can significantly slow throughput.
Synchronization has a cost
- ·
Putting
synchronized all over the place does not ensure thread safety.
- ·
Putting
synchronized all over the place is likely to deadlock.
- ·
Putting
synchronized all over will slow your code and prevent it from running when it
should. This accounts for memory leaks.
3.1.8.
Technical points
Apart from
the standards mentioned already following should be considered while writing
java
- ·
Instance
/class variables should not be made public as far as possible.
- ·
A
constructor or method must explicitly declare all unchecked (i.e. runtime)
exceptions it expects to throw. The caller can use this documentation to
provide the proper arguments.
- ·
Unchecked
exceptions should not be used instead of code that checks for an exceptional condition.
e.g. Comparing an index with the length of an array is faster to execute and
better documented than catching arrayOutOfBoundsException.
- ·
If
Object.equals is overridden, also override Object.hashCode, and vice-versa.
- ·
Override
readObject and writeObject if a Serializable class relies on any state that
could differ across processes,including,in particular,hashCodes and transient
fields.
- ·
If
clone() may be called in a class, then it should be explicitly defined, and
declare the class as implements Cloneable.
- ·
Always
use method equals instead of operator == when comparing objects. In particular,
do not use == to compare Strings unless comparing memory locations.
- ·
Always
embed wait statements in while loops that re-wait if the condition being waited
for does not hold.
- ·
Use
notifyAll instead of notify or resume when you do not know exactly the number
of threads which are waiting for something
- ·
When
throwing an exception, do not refer to the name of the method which has thrown
it but specify instead some explanatory text.
- ·
Document
fragile constructions that have been used solely for the sake of optimization.
- ·
Document
cases where the return value of a called method is ignored.
- ·
Minimize
* forms of import Be precise about what you are importing.
- ·
Prefer
declaring arrays as Type[] arrayName rather than Type arrayName[].
- ·
StringBuffer
should be preferred for cases involving String concatenations. Wherever required
String objects should be preferably created with a new and not with the help of
assignment, unless intentionally as they remain in the String pool even after
reference is nullified.
- ·
All
class variables must be initialized with null at the point of declaration.
- ·
All
references to objects should be explicitly assigned ‘null’ when no more in use
to make the objects available for garbage collection.
- ·
As
far as possible static or class fields should be explicitly instantiated by use
of static initializers because instances of a class may sometimes not be
created before a static field is accessed.
- ·
Minimize
statics (except for static final constants).
- ·
Minimize
direct internal access to instance variables inside methods.
- ·
Declare
all public methods as synchronized.
- ·
Always
document the fact that a method invokes wait.
- ·
Classes
designed should be easily extensible. This will be very important in the event
that the currently designed project needs to be enhanced at a later stage.
- ·
It
is very important to have the finally clause (whenever required) because its
absence can cause memory leakage and open connections in a software.
Thanks
