Sunteți pe pagina 1din 35

Java Coding Standard

Software Development:
Java Coding Standard
Author:

Creation Date:

August 11, 2014

Last update:

August 11, 2014

Versin:

0.1.0

Copyright 2014. oration


All Rights Reserved

Approval:

Page 1

Java Coding Standard

Changes Record

Date

Author

Version

Change Description

Reviewers
Name

Position

Page 3

Java Coding Standard

Content

Java Coding Standard.....................................................................4


1- Prefacio................................................................................................... 5
General Purpose......................................................................................5
Specific Goals.......................................................................................... 5
2- Naming Standard for Language Elements...............................................6
3- Source File Organization..........................................................................8
3.1
3.2
3.3
3.4
3.5

Header for Classes and Interfaces.........................................................8


Package definition sections...................................................................9
Importing Libraries section (import)...................................................9
Statement and Definition of Classes and Interfaces...........................10
Statement and Definition of private Classes.......................................10

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

5- Best Practices for Java Coding...............................................................18


6- Anexo 1. Prefixes for Common Data Structures and Widgets................19
6.1 Prefixes for common Data Structures..................................................19
6.2 Widgets Naming Prefixes..................................................................... 19

7- Annex 2. Package Hierarchy..................................................................20


8- Annex 3. Code Documentation..............................................................22
8.1 Documentation Comments..................................................................22
8.1.1 Documentations of Classes and Interfaces.......................................23
8.1.2 Documentations for Methods and Member variables........................23
8.2 Implementation Comments.................................................................24

9- Anexo 4. Instructivo de Configuracin de IntelliJ IDEA para Estilo de Cdigo


.................................................................................................................. 25
Setting Indents and Tabulation..................................................................25
Text Wrapping configuration...................................................................... 26

Page 5

Java Coding Standard

Java Coding Standard

Page 7

Java Coding Standard

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

Java Coding Standard

Page 11

Java Coding Standard

2- Naming Standard for Language Elements (CamelCase 1)


This section describes how to name the elements of the Java programming language,
which is used for the development of the company's products.
In general, you should use complete English words for the naming of language
elements also must use lowercase lettersexcept for the initial letter of the classes
and the first letter of non-initial words in the elements.
It must consider the following general guidelines:

Use complete words and phrases.

Use consistent terminology applicable to the domain

Use lowercase and uppercase letters in mixture to enhance understanding.

Avoid names that are similar with only difference in the "case" of the letters.

Think about refactoring if the Unit/member name is longer than 20 characters.

The following table summarizes the standard of appointment to the basic elements of
the language:

Item

Naming Policy

Example

Arguments /
Parameters

Use complete English words


describing the object being
passed.

customer, employee,
salary, customers,
employees, link, links,
networkId

Attributes of
classes

Use complete words in English


with all first letters of initial
words not capitalized.

firstName, lastName,
linkName, serviceName

Classes

Use complete descriptions in


English with the first letter
capitalized.

Customer, Employee,
Network,
BackboneNetwork

1 http://en.wikipedia.org/wiki/CamelCase

Page 13

Java Coding Standard

Item

Naming Policy

Example

Do not use underscores to


separate the names.

Member /
methods
Functions

Use complete English words


describing what the method does
(usually <verbNoun>).

getName (), setName (...),


init (), openFile (),
addLink (), removePort ()

Prefix the word "get" to capture


features and attributes and "set"
for writing functions.
Never start with capital letters.
Do not use underscores to
separate words.

Local Variables

Use complete English


descriptions.
Do not overwrite local variables
with the name of public class
attributes.

customer, service, link,


TotalBandwidth,
serviceCost, vcCustomers,
htObjectNames.
Variables for cycle
counters: j, i, n, co, etc.

Do not use the underscore


character to separate words.
Use prefixes set out in Annex 1
for the structures or data types
described there. Variables that
are used to cycles, especially
accountants, should have simple
lyrics and name.

Interfaces

Using a full description describing the


concept that encapsulates the
interface.

Customizable, Executable,
Adaptor, Singleton.

It is Common to use the suffixes


"able", "ible" or "er" but not required.

Packages

Use full English words, all


lowercase.For global packages,
reverse the internet domain
name (com.consensus.) and
concatenate the package name.

com.consensus.common.g
ui,
com.consensus.common.c
ore, com.consensus.sales

Page 15

Java Coding Standard

Item

Naming Policy

Example

Follow the package hierarchy


defined in Annex 2.

Source Files

The files should be named in the


same way that the class .java

Customer.java,
Service.java

Graphics /
Widgets
Components

Using a full description similar to


local variables named with the
difference that they must have a
prefix describing the type of
graphical component English as
specified in Annex 1.

pbSave, lstCustomer,
cbServiceType, plLinks

Constants

Use descriptions (Abbreviations


significant) in English separating
each word with an underscore
and all upper case.

MAX_LINKS, MIN_USERS,
DB_PORT, DEFAULT_TYPE

Exceptions

e or ex letters will generally


be used to represent exceptions.

e, ex

Page 17

Java Coding Standard

3- Source File Organization


Each Java source (.java file) file must contain only one public class or public
interface.
If it is the case, private classes should be located at the end of the definition of the
public class in the same source file.
The structure of the source files should be as follows:
1. Declaration of "package".
2. Declaration "import".
3. Header: Comments for this class or interface.
4. Declaration and definition of the class or public interface.
5. Declaration and definition of private classes.
The following figure illustrates an example of the source file organization of a class or
interface:
package com.consensus.pam.server.accell;
import com.consensus.pam.shared.accell.ColumnDefinition;
import com.consensus.pam.shared.accell.TableBeanModel;
/**
* DBBroker
* Controls operations against the database
*
* @author
* @since
May 13, 2014
*
* All rights reserved.
* (C)
*/
public class DBBroker
{

}
/**

*/
private class DBMetaData
{

Page 19

Java Coding Standard

Each of the sections that make up the source file must be accompanied by at least a
blank line.
Below each section details.

3.1 Header for Classes and Interfaces

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.
*
*/

Tabla 1. Header for Classes and Interfaces

Page 21

Java Coding Standard

This template should be respected as such as shown in Table 1 contains additionally,


technical information necessary to document the class.
<Class Name>contains the exact name of the class that is being implemented.
<Description of the class>contains a complete description of the class including
its usage, pre and post conditions. If necessary, the developer may include small
examples and manuals.
<Author email/Name>contains the full name of the author of the initial class.
<Date of Creation>contains the date of creating on of the class format DD-MMMYYYY. Where MMM is an abbreviation letters of the month in the year. For example:
15-APR-2014, 01-DEC-2012.

3.2 Package definition sections

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.

3.3 Importing Libraries section (import)

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:
-

General JDK packages.

Third party packages

companys own packages

The definition of "import" starts in column 1 without left indented.


There should be leading (blank lines) between the sentences "import"

Page 23

Java Coding Standard

3.4 Statement and Definition of Classes and Interfaces

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"

Definition Statement of the class or interface

Deployment
documentation
(/ * ... * /)

Class or interface public documentation

StaticVariables

Preferably in the following order: public


(public), protected (protected), package (no
access modifier), and then private (private).

Instance Variables

Preferably in the following order: public


(public), protected (protected), package (no
access modifier), and then private (private).

Constructors

Methods

The sorting criteria methods must be fully


functional, that is, the order may facilitate
reading the code given the final functionality
of the class.This means that a private method
can be between two public for instance.

Page 25

Java Coding Standard

3.5 Statement and Definition of private Classes

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

Java Coding Standard

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.

4.2 Indents (Indentation)

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:
-

New line after a comma.

New line before an operator.

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.

Below some examples:

Page 29

Java Coding Standard

Example 1:Alignment of the invocation of a method.


someMethod(parameter1, longExpression2, longExpression3, longExpression4,
longExpression5);
result = someMethod(parameter1, longExpression2, longExpression3, longExpression4,
longExpression5);

Example 2: Alignment of arithmetic expressions.

longValue1 = longValue2 * longValue3 (MAX_VALUE / longValue4 )


+ longValue6 * INT_CONST;
longValue1 = longValue2 * ( longValue3 + longValue4 * longValue5
+ longValue6 * INT_CONST);

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

Programs written in Java can contain two kinds of comments: implementation


comments and documentation comments.
Implementation comments usually contain internal technical information and code
are delimited by / * ... * / for blocks (multiple lines) and // to a single line.
Documentation comments are specific to Java and contain information on how the
class (user documentation for the class), or interface method is used. Are delimited
by / ** ... * /. Tools like JavaDoc to generate HTML files with user documentation of
classes use such comments.

Page 31

Java Coding Standard

4.3.1 Implementation Comments

The number of lines they contain governs these comments.


-

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;

// arg1 can be null

// The result variable will contain the value in percentage


result = someMethod2(MAX_VALUE, arg2);

4.3.2 Documentation Comments

For a detailed description of how to implement documentation comments, refer to


Annex 3: "Documenting the code".
Documentation comments describe classes, interfaces, constructors, methods and
properties.
Each comment is located between the characters / ** and * / with one comment per
class, method or property and should appear just before the declaration, for example:

public class className


{
/**

Place here the documentation comment


*/
public void methodName()
{
..
}
}

Page 33

Java Coding Standard

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.

Location of statements:Always element declarations must be the first line in a


block of code.The only exception to this rule should be the counter variables in
"for" statements.

4.4.1 Classes and Interfaces Statements

Follow these general rules for the declaration of classes and interfaces:

Page 35

Java Coding Standard

All Public class declaration must be accompanied by documentation comments.

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

public class Employee


{

private void getName()


{

if (100 < value2)


{

}
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

public void getSalary ()


{

Page 37

Java Coding Standard

Item

Description

Examples

enclosed in brackets
"{...}".

statements;
}

The brackets must be


on separate lines.
Simple sentences must
be aligned indent the
right brackets.

for(Condition)
{
statements;
if(Condition)
{
statements;
}

}
Statement "return"

The "return" statement


must enclose the return
value in parentheses.

r eturn(Value2);
return;

If statements, if-else, ifelse if, if-else if-else

Should have the form


illustrated in the
example.

i f(Condition)
{
statements;

The "if" statements


should always use
brackets even when the
domestic statement is
simple.

}
else if(Condition)
{
statements;
}
else
{
statements;
}

Page 39

Java Coding Standard

Item
Statement "for"

Description

Examples

In general should have


the following form:

f or(Int c = 0; c< MAX;+


+ c)
{

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

} while (count < MAX);

statements;
} while (condition);
Statement "switch"
In general should have
the following form:

switch(Color)
{

Page 41

Java Coding Standard

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

public void someMethod


()
{
doSomething ();

try

statements;

doSomething1 ();

catch(Excepiones)
}

catch(Exception e)

statements;

Statement "finally"

Must be aligned with the


immediately preceding
sentence of the code
block.
The block "finally" would
apply the same

processError (e);
}
}
finally

Page 43

Java Coding Standard

Item

Description
considerations to the
block syntax "catch".

Examples

{
...
}

4.4.3 Use of White Spaces

You must use spaces and blank lines as follow:


-

Use two (2) blank lines between definitions of classes or interfaces.

Use one (1) blank line:


o

Between the definition of methods.

Between the declaration of local variables and the first statement in a block
of code.

Before a comment line or block.

Between logical sections of a method to improve readability.

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.

The expressions in the sentence "for" must be separated by a space.

See the following example

a = c + d;
n = (a + b) (d * f) / (MAX * g);

while (f++ < MAX)


{
n++;
}

f += (int) (f * d);

for (int a=0; a < MAX; a++)


{
d = myMethod((int) b, (long) b);
System.out.println(Value: + d + \n);
}

Page 45

Java Coding Standard

5- Best Practices for Java Coding

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

Use private member variables. Use getter and


setter functions to set ("setXXX ()") and get
("getXXX ()") the contents of private variables of
the class.

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:

public boolean isPersistent ()


public boolean isActive ()
4

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":

getPorts () -> Gets the collection of ports


setPorts () -> Set the ports collection

Page 47

Java Coding Standard

insertPort () -> Enter a port collection


deletePort () -> Removes a port collection
addPort () -> Create a port to the collection
getPort () -> get a port of the collection.

5
6

Static Variables
Static blocks

Public Methods

Scope of Variables

Concatenation
Strings

Static variables should always be initialized.


Using static blocks of code to initialize static
variables result of computations.
Minimize the public interface of classes, ie only
declare public methods required by any other
class.
Declare the variables in the right block of code
that will be used.

of
Avoid using the + operator
strings.
Use
the
operator
"StringBuffer" class instead.

to concatenate
"append"
the

If synchorinization is not used, use the new class


StringBuilder to improve String operations
performance.

Page 49

Java Coding Standard

6- Anexo 1. Prefixes for Common Data Structures and Widgets


This section defines the prefixes to use for naming of certain common data structures
and graphics components.
6.1 Prefixes for common Data Structures

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

6.2 Widgets Naming Prefixes

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

Java Coding Standard

Toggle
Button
Window
Button

Tb

tbHide

wnd
btn

wndMain
btnAdd, btnDelete

Page 53

Java Coding Standard

7- Annex 2. Package Hierarchy

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

Sales, customer and order Management.

pricing

Price calculation engine for products and


services

products

Product lifecycle management

inventory

Inventory management

fraud

Fraud control management

partners

Partners relationship management. SLAs,


Aggrements.

platform

Comprise all technical core-components.

Package Name

Core-Components

Page 55

Java Coding Standard

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

Module security management product.

businessrule

Runtime and administration of business


rules.

configuration

Module configuration management and


configuration of the modules.

common

Contains utility classes between modules.

reporting

Reporting component

scripting

Functions engine

logging

Logging helper clases

scheduling

Job scheduling

monitoring

Snmp based monitorable capabilities

workflow

Workflow engine

Package and classes commonly used for the


module. As controllers, servers and tooling classes
that implements technical aspects of the module
as security, distribution, connectivity, etc.
Contains classes that represent business objects
"Business Objects" which implement most of the
functionality of the module and the engines.
Contains classes that implement the inter-module
APIs commonly called "Business Services". These
classes have the least amount of logic and are
based on "Business Objects" to provide services to
other modules.
Contains
packages
and
classes
for
the
presentation layer module as applets, windows,
components, beans, etc. Additionally it contains
classes implementing presentation logic.
Contains JPA entities for the data model.
Contains REST web services that the module expose to
external applications. Its functionality must be based on

Page 57

Java Coding Standard

the invocation of business services.

Page 59

Java Coding Standard

8- Annex 3. Code Documentation

This section defines the rules to document programs written in Java.

There are three types of comments within a program. Documentation comments,


reviews implementation and obsolete comments or temporary code.

8.1 Documentation Comments

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

@ param name description

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

Java Coding Standard

since

@seeclassname

Interface,
Method
Interface,
Method

Class,
Class,

@see classname # method

version text

Interface, Class

Indicates version or date on


which the item is valid.
Generates a hyperlink to the
documentation
of
the
specified class or method to
expand the documentation for
this
element.
You
must
specify the full name of the
class or method.
Indicates the version of the
class or interface.

8.1.1 Documentations of Classes and Interfaces

The section 3.1 of this document illustrates the header template is both a description
of each of its components.

8.1.2 Documentations for Methods and Member variables

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

public synchronized int setData(byte[] buf, int offset, int length)

Java Coding Standard

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"

8.2 Implementation Comments

Implementation comments are intended to help the developer to understand what


the block of code does and how. For this type of comments, it must use the singleline comments " // ".
The level of detail of this type of documentation is subject to the discretion of the
developer, but in general, should be documented in the following situations:
-

Control structures Reviews functionality of the method.

Local variables of importance.

Definition of complex data structures or collections as vectors, hash tables,


classes, etc.

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

Java Coding Standard

Page 67

Java Coding Standard

9- Annex 4. IDE specific Code Style templates

Aspartofthisdocument,aIDEspecifictemplateforcodestylingwillbeprovidedtodevelopers.

Page 69

S-ar putea să vă placă și