Documente Academic
Documente Profesional
Documente Cultură
Software Development:
Java Coding Standard
Author:
Creation Date:
Last update:
Versin:
0.1.0
Approval:
Page 1
Changes Record
Date
Author
Version
Change Description
Reviewers
Name
Position
Page 3
Content
4- Coding Standards..................................................................................11
4.1 General Rules...................................................................................... 11
4.2 Indents (Indentation)........................................................................... 11
4.3 Comments........................................................................................... 12
4.3.1 Implementation Comments..............................................................12
4.3.2 Documentation Comments...............................................................13
4.4 Statements.......................................................................................... 13
4.4.1 Classes and Interfaces Statements...................................................14
4.4.2 Statements....................................................................................... 14
4.4.3 Use of White Spaces......................................................................... 16
Page 5
Page 7
1- Preface
General Purpose
This document defines the standards and rules for coding Java programs for oration.
The purpose of defining certain standards and norms is to improve the
maintainability, reliability and extensibility of our applications through practices that
promote the development of maintainable, legible and unambiguous code and
facilitates collaboration.
Specific Goals
This document has the following specific goals:
1. Define the naming standard for the elements of the Java Language.
2. Define the rules for writing programs such as documentation (captions and
comments), naming of members, tabulation and the organization of the
components of a program, among others.
3. Define general rules for program development.
Page 9
Page 11
Avoid names that are similar with only difference in the "case" of the letters.
The following table summarizes the standard of appointment to the basic elements of
the language:
Item
Naming Policy
Example
Arguments /
Parameters
customer, employee,
salary, customers,
employees, link, links,
networkId
Attributes of
classes
firstName, lastName,
linkName, serviceName
Classes
Customer, Employee,
Network,
BackboneNetwork
1 http://en.wikipedia.org/wiki/CamelCase
Page 13
Item
Naming Policy
Example
Member /
methods
Functions
Local Variables
Interfaces
Customizable, Executable,
Adaptor, Singleton.
Packages
com.consensus.common.g
ui,
com.consensus.common.c
ore, com.consensus.sales
Page 15
Item
Naming Policy
Example
Source Files
Customer.java,
Service.java
Graphics /
Widgets
Components
pbSave, lstCustomer,
cbServiceType, plLinks
Constants
MAX_LINKS, MIN_USERS,
DB_PORT, DEFAULT_TYPE
Exceptions
e, ex
Page 17
}
/**
*/
private class DBMetaData
{
Page 19
Each of the sections that make up the source file must be accompanied by at least a
blank line.
Below each section details.
The header will contain class information and a section to record the changes made
to it during its life cycle. The template of the header must be:
/**
* <Class Name>
* <Class Description>
*
* @author
<Author e-mail>
* @since
<Creation Date>
*
* All Rigths Reserved.
* Consensus Corporation.
*
*/
Page 21
In this section the package that owns the class is defined.All public class must belong
to a package.
The definition of "package" starts in column 1 without left indented.
Packages must obey the hierarchy defined in Annex 2.
This section describes the packages and classes where you should find the references
used in the specified class.You must define a single statement "import" per line and
preferably in the following order:
-
Page 23
This section declares and defines the class contained in the source file. It should start
with reserved words corresponding to the access modifiers and their typein column 1
without left indented.
The open and close brackets must follow the C-Style convention, it means, open
and close brackets for every statement block must be in a new line.
The reserved words "extends" and "implements" must be in the same line of the
class declaration.
Inside the class definition, use the following order for the elements comprising:
Statement "class" or
"interface"
Deployment
documentation
(/ * ... * /)
StaticVariables
Instance Variables
Constructors
Methods
Page 25
The declaration and definition obey the same rules described in the previous section,
with the addition that they should always go after the public class definition.
Page 27
4- Coding Standards
This section defines the basic rules for coding Java programs taking into account each
of the elements of the language syntax.
4.1 General Rules
You should consider the following general rules for writing programs:
- The lines of code should have a maximum length of120 characters.If you need to
use more characters, nor follow the more "Indent statements multiline".
- If possible try to limit the definition of class s to a maximum of1000 lines.
-Think about refactoring if the class requires more than 1000 lines of code.
- Use documentation and implementation comments over the definition of classes,
interfaces and components.
It must be use the blank characters instead of the tab carcter for indentation.
It must be use four (4)space characters for tabbing.
The following are general rules for setting indents in long expresions:
-
In expression, align the new line with the beginning of the expression at the
same level on the previous line.
In the method invocation, align the arguments of the second line onwards from
the column of the first argument. Should try to use few arguments in methods.
Page 29
For method declarations that require more than one line, use a tab to its
arguments from the second line. See the following example::
public static synchronized void someLongNamedMethod(argument1, argument2,
argument3, argument4, argument5, argument6, argument7, argument8,
argument9, argumen10)
{
4.3 Comments
Page 31
To comment on more than one line use the structure shown in the following
example:
/*
This piece of code will be left intentionally commented.
var1 = someMethod(val2, val3);
*/
For single-line comments should use the scheme shown in the following example:
value1 = someMethod2(arg1, arg2) + MAX_VALUE;
Page 33
Documentation comments can not be located within blocks of code because Java
associates with the first statementafterthe comment.
If it is required to give information about a class, method or variable that is not
relevant as public documentation for users of the same, use implementation
comment.
Do not comment obvious methods even if they are public methods. This is the case
for getter and setter methods.
4.4 Statements
Following there is a series of general rules listed for the declaration of program
elements:
-
Inline Statements: You must declare only one item per line to facilitate
documentation for example:
int salary = 0;
// Initial Salary
int average = 100;
// Average
long workDays = 365; // Working days
// Avoid the following
int salary = 0, average;
Initialization: Initialize the variables in the same place unless you declare the
initialization value is the result of a computation with other variables.
Follow these general rules for the declaration of classes and interfaces:
Page 35
There should be no space between the method name and the parenthesis "("
Opening.
The left bracket both the class definition andthecode block should be on the line
following the statement, aligned in the initial column of the same and be the only
statement on that line (C-Style).See examples below
}
else
{
...
}
The above standard must be met even for null code block "{} ".
The statement of the methods must be separated by at least one blank line
4.4.2 Statements
The following table summarizes the rules around the basic coding language
statements:
Item
Simple Sentences
Description
Each line should contain
at most one statement
Examples
++ var1;
var2--;
avoid:
++ var1;
var2--;
Compound Sentences
A compound statement
or block of c ode is a set
of simple statements
Page 37
Item
Description
Examples
enclosed in brackets
"{...}".
statements;
}
for(Condition)
{
statements;
if(Condition)
{
statements;
}
}
Statement "return"
r eturn(Value2);
return;
i f(Condition)
{
statements;
}
else if(Condition)
{
statements;
}
else
{
statements;
}
Page 39
Item
Statement "for"
Description
Examples
for(Init, condition,
update)
statements;
}
{
statements;
}
Statement "while"
In general should have
the following form:
while (condition)
{
statements;
while (condition)
}
{
statements;
}
Statement "do-while"
In general should have
the following form:
do
{
do
someMethod (count +
+);
statements;
} while (condition);
Statement "switch"
In general should have
the following form:
switch(Color)
{
Page 41
Item
Description
Examples
switch(Condition)
case RED:
newcolor=GREEN;
ABC case:
break;
statements;
case GREEN:
break;
newcolor=RED;
DEF case:
break;
statements;
default:
break;
newcolor= BLACK;
default:
break;
statements;
break;
}
Statement "try - catch"
The sentence "try-catch"
must have the following
format:
try
try
statements;
doSomething1 ();
catch(Excepiones)
}
catch(Exception e)
statements;
Statement "finally"
processError (e);
}
}
finally
Page 43
Item
Description
considerations to the
block syntax "catch".
Examples
{
...
}
Between the declaration of local variables and the first statement in a block
of code.
Use one (1) blank space between reserved words and opening parenthesis.
Use one (1) space after a comma in the list of arguments or parameters.
All binary operators (=, +, /, *, -, etc) (.) Except point should be separated from
their operands by a blank space.
Unary operators such as "++" and "-" should not be separated from their
operands.
a = c + d;
n = (a + b) (d * f) / (MAX * g);
f += (int) (f * d);
Page 45
This section presents a series of "Best Practices" for coding Java programs. The
developer should try to join up to these suggestions and document situations that
cannot be applied.
The following table summarizes the suggestion:
Numb
er
1
Applies To:
Description
Member Variables
Conditional
In conditional expressions prefer to post
constants on the left side of the conditional
operator.For example:
if (MAX == var1)
if (0 <var2)
3
Boolean Variables
Use the prefix "is" in the name of methods that
obtain the value of Boolean variables of a class.
For example:
Collections
It is recommended that member variables have
public accessor methods for handling. We
recommend using the following names for such
methods: Imagine we knew a member variable
collection of ports "Port":
Page 47
5
6
Static Variables
Static blocks
Public Methods
Scope of Variables
Concatenation
Strings
of
Avoid using the + operator
strings.
Use
the
operator
"StringBuffer" class instead.
to concatenate
"append"
the
Page 49
Type
Vector
Prefix
vc
Hashta
ble
Hashma
p
Array
ht
List
Set
lst
st
Example
vcCustomers
vcLinks
vcNames
htCustomers
htNetworks
hmCustomers
hmNetworks
arNames
arEmployees
lstItems
stCounters
hm
ar
Component
Dialog
Frame
Panel
Scroll Panel
Split Panel
Tabbed
Panel
Toolbar
Push Button
Combo Box
List
Menu
Menu Item
Slider
Text Field
Label
Progress
Bar
Table
Tree
Text Area
Radio
Button
Check Box
Prefix
dlg
frm
pnl
scp
spl
tbp
Example
dlgOpenFile
frmMain
pnlMainPanel
scpCustomerInfo
splMainFrame
tbpLinkInfo
tlb
Pb
cbx
Lst
mn
mnt
sld
Tf
Lb
pgb
tlbMainToolbar
pbOk, pbCancel
cbxStatus
lstOptions
mnOperations
mntActivate, mntPrint
sldSeparator
tfLinkName
lbLink
pbgSaveOperation
tbl
Tr
txt
Rb
tblAdditionalData
trAffection
txtComments
rbPassive
Cb
cbInactive
Page 51
Toggle
Button
Window
Button
Tb
tbHide
wnd
btn
wndMain
btnAdd, btnDelete
Page 53
This section describes the hierarchy that must be followed when defining new
packages.
Mainly, the hierarchy is based on a functional approach to organize the packages.
The following table illustrates this hierarchy.
Package
Description ng
com.consensus. <module>
<Module> describes the functional module. The package
names for the respective modules are:
Package Name
Functional Module
sales
pricing
products
inventory
Inventory management
fraud
partners
platform
Package Name
Core-Components
Page 55
com.consensus.
<module>.common
com.consensus. <module>
.bo
com.consensus. <module>
.bs
com.consensus. <module>
.gui
com.consensus. <module>
.data
com.consensus. <module>
.ws
security
businessrule
configuration
common
reporting
Reporting component
scripting
Functions engine
logging
scheduling
Job scheduling
monitoring
workflow
Workflow engine
Page 57
Page 59
These comments are used to describe the definition of classes, interfaces and
member functions or methods.This description should cover aspects such as class or
method: what it does, how it does, why it is done, who did it, among others.
To generate documentation purposes in industry standard format, these comments
should use the labelsbased on "JavaDoc".The following table summarizes the most
frequently used tags:
Tag
@ author name
Used In
Interface, Class
deprecated
Interface,
Method
Methods
exception
description
name
Method
@ return Description
Method
Class,
Purpose
Indicates the author of the
code element. You must use a
label by author.
Indicates an obsolete element
should not be used.
Indicates the exceptions that
a method triggers. You must
use a label for each exception
and describe the full name of
the class.
Describe each of the method
parameters. Indicate its type.
Use
a
label
for
each
parameter.
Indicates the return value of
the method if any. You must
indicate the type of the
return
value
and
their
possible use.
Page 61
since
@seeclassname
Interface,
Method
Interface,
Method
Class,
Class,
version text
Interface, Class
The section 3.1 of this document illustrates the header template is both a description
of each of its components.
You must document the following aspects of the methods and member variables in
classes as applicable:
1. What and why the method or variable does what they do. Documenting what
the method does makes easier for other developers to decide whether to
reuse the method. Document why such a thing is done, put in context the
developer trying to maintain the code and avoid rewriting not understand the
functional origin of the method.
2. What you must pass a method as a parameter. Should indicate what
parameters will be passed to a method, type and description and how they
will be used within the method. (See JavaDoc param).
3. What the method returns.
4. Exceptions that the method fires. You should document each and every one of
the exceptions that the method fires so the developer will know which
exceptions must be captured.
5. Examples of how to invoke and use the method. In the case of complex
methods, it is advisable to give the user of the class invocation examples
where the origin of the s parameters and possible return values are displayed.
The following figure shows an example of using c ow JavaDoc tags to document the
methods of clases:
/**
*Setthedatabufferforthepacket.
*
*@parambufdatabuffer.
*@paramoffsetoffsetinsidethebuffer
*@paramlengthLengthofthebuffer.
*
*@exceptionNullPointerExceptionifargument<p>buf</p>isnull
*
*@returnReturnsaIntegerwiththeerrorcode
*
*@see#getData
*@see#getOffset
*@see#getLength
*
*@sinceJDK1.2
*/
Page 63
The order in which labels must be written has no technical relevance, however, the
following order for consistency and better understanding of the code is suggested:
1. Description of the method. Free text of varying length. You can use HTML tags to
highlight text or give better appearance to the description of the method.
2. Specification of the method. Label "deprecated".
3. Parameter Description. Tag "param".
4. Description of exceptions. Label "exception"
5. Description of return. Tag "@ return"
6. References to other documentation. Label "@see".
7. Specifying the validity of the method. Label "since"
It is good practice to use the word " // TODO : ", to remind the developer of certain
functions or actions that must be coded in the future. Some text editors or IDEs allow
you to see all reviews of this type in a given source file.
Page 65
Page 67
Aspartofthisdocument,aIDEspecifictemplateforcodestylingwillbeprovidedtodevelopers.
Page 69