java standards

8/13/2019 Java Standards

1/17

Proprietary and confidential. 2005 Perot Systems. All rights reserved.www.perotsystems.com

People. Processes. Technology. Results.

Security Classification: Perot Systems Technology Services Confidential

This is a controlled document. Unauthorized access, copying and replication is prohibited. This document must not be copied in whole or part by any means,without the written authorization of Head of Quality Assurance Group, Perot Systems Technology Services.

Perot SystemsTechnology Services

Plot # 3, Sector 125NOIDA - 201301Uttar Pradesh, India

JAVA Coding

Standards(SG620)

Version : 1.5Released on : 29th June 2005

Author : Ashish GuptaLast Revised by : Namita Sehgal


2/17

SG620:JAVA Coding Standards Confidential Page 2 of 17Version 1.5

Contents

1. Overview.. 3

1.1.Intended Audience .......................................................................................31.2.Acronyms & Definitions ..............................................................................31.3.Responsibilities..............................................................................................31.4.Quality Record Forms ..................................................................................31.5.References ......................................................................................................3

2. Introduction ..3

2.1.Conventions...................................................................................................4

3. Naming Conventions 4

3.1.Package...........................................................................................................43.2.Class................................................................................................................43.3.Interface..........................................................................................................43.4.Methods..........................................................................................................53.5.Variables.........................................................................................................53.6.Member variables..........................................................................................53.7.Constants........................................................................................................53.8.Accessors and Mutators...............................................................................53.9.Exceptions ......................................................................................................5

3.10. Swing components Naming convention..........................................53.11. Enterprise Java Beans Naming convention......................................73.12. JSP / Servlet Naming convention .....................................................7

4. Header & Footer ..7

4.1.Header ............................................................................................................74.2.Footer..............................................................................................................8

5. Documentation .8

6. Format .9

7. Layout .11

8. Best Practices (JSP/ Servlet/ EJB inclusive) .11

9. AMENDMENT HISTORY .16


3/17


1. OverviewThe purpose of programming standards is to support the development ofapplications that are consistent and well written. Standards and guidelineshelp developers to create a code base with a uniform presentation, whichleads to code that is easy to understand, easy for other developers to use andeasy to maintain. Standards and guidelines also help developers to avoid thecommon pitfalls of Java that leads to code that is robust, reliable and portable.

Coding standards for Java are essential and should be adopted to achieve thefollowing goals.

Facilitate joint development

Avoid common pitfalls Maintainability

Reliability

Readability/Comprehensibility

1.1. Intended Audience

This guideline is intended for use by developers and reviewers in Java.

1.2. Acronyms & Definitions

Acronym Descript ion

PS TS Perot systems Technology Services

DCA Document Control Administrator

VER Version

1.3. Responsibilities

None

1.4. Quality Record Forms

None

1.5. References

None

2. IntroductionIn the beginning it was very simple, a programmer sitting at his deskchurning away code in his garage. He was one with his code, he knew whereeverything was, didn't have any uses for UMLs, structures or comments, andthere were absolutely no co-workers, bosses and people like me writing

documents like this telling you what you should and shouldn't do. It was the


4/17


golden days, where every programmer knew how to write assembler in anylanguage, comments were for wine critics and programming was an art.

Today it's difficult to imagine any type of large-scale system with 1

programmer on it. The modern day programmer spend less time coding,more time collaborating, after all it's all about the team. Communicationbetween programmers is a key factor in a successful software shop. Everyoneneeds to be kept on the same page throughout the cycle. Amongst differentlevels of systems, source code plays a vital role, this is the heart of our systemand programmers/developers should not have too much trouble navigatingthrough it.

Coding standard is not there to play gestapo and force upon us an idealistic"standard", stripping us of our style and personality, this is there as a guide,creating a commonality amongst programmers to increase readability,productivity, maintainability, robustness and professionalism. Imagine a

bunch of construction workers refusing to conform to one "constructionstandard", allowing different types of building methods for everyone, wouldwe feel safe walking into such building? Software should no less be different.We all depend on each other's work to make come about something greater.

2.1. Conventions

The conventions followed in the document are the same as specified in theDocumentation Standards SG510.

3. Naming Conventions

3.1. Package

PS TS written code should always begin with com.PS TS unless specifiedotherwise.

Capitals should not be used in the packages names.

Automated unit test cases using frameworks like JUnit should be placed in a parallel

package hierarchy in a separate source folder. Using the same package naming

convention for them would cater to easy testability of complex protected methods.

3.2. Class

Class names should be descriptive nouns or noun phrases, not overlylong, with first letter of every word in uppercase. Some examples ofconforming names are

SecurityManager

ClassLoader

3.3. Interface

Same naming convention as that for class, usually ending in suffixes likeable, or Listener. Some examples of conforming names are

Loggable

Nameable Runnable


5/17


QueueListener

ActionListener

3.4. Methods

Method names should be verbs or verb phrases, with first letter in lowercase and first letter of every subsequent word in uppercase. Someexamples of conforming names are

log

processRequest

certify

3.5. Variables

Variables should have names that are nouns, noun phrases, or

abbreviations for nouns. Names of fields that are not final should have thefirst letter in lower case and first letter of the subsequent words inuppercase. Some examples of conforming names are

o logger

o logManager

3.6. Member variables

Member variables should have m_ appended to them. Some examplesof conforming names are

o m_logger

o m_logManager

3.7. Constants

The names of constants in interface types and final variables of class typesshould be a sequence of one or more words, acronyms, or abbreviations,all uppercase, with words separated by underscore "_" characters. Someexamples of conforming names are

o MIN_VALUE

o MAX_VALUE

3.8. Accessors and Mutators Accessors should be named getProperty (where property is the name of

the member they are supposed to retrieve)

Mutators should be named setProperty (where property is the name ofthe member they are supposed to mutate)

3.9. Exceptions

Exceptions should follow the same naming conventions as those fornaming classes, they must additionally be suffixed by the word Exception

3.10. Swing components Naming convention


6/17


A control or a component name should have two parts. First part or theprefix should help in identifying the type of the control. Second partshould identify the functionality or the purpose of the component. Thename should additionally conform to conventions for variables and

member variables. Use the following table to identify prefixes forparticular Swing components

Control/ Component Type Prefix

Button btn

Check Box cbx

Color Chooser (or Dialog) clrdial

Combo Box cmb

Desktop Pane dskpan

Editor Pane edtpan

File Chooser (or Dialog) fldial

Frame fr

Internal Frame intfr

Label lbl

Layered Pane lypan

List lst

Menu Bar mnubr

Option Pane optpan

Panel pnl

Password Field pwdf

Popup Menu ppmnu

Progress Bar prgbr

Radio Button rdbtn

Scroll Bar scbrScroll Pane scpan

Separator sep

Slider sldr

Split Pane splt

Tabbed Pane tbpan

Table tbl

Text Area txta

Text Field txtf


7/17


8/17


The keyword $ID $ above will expand into the Versioning repositoryidentifier for the code file.

4.2. Footer

Every Java Code file written by PS TS should contain the modification login its footer. The use of key word $log $ is recommended. In versionmanagement systems like CVS and PVCS this will auto expand into anycomments entered during a commit to the versioning system. Thefollowing should be the footer /*

* $log $

*/

5. Documentation Collaboration requires we communicate at every level possible, especially

in our source code. Sometimes the very programmers who wrote the codethemselves forget what they wrote. Documentation will save your timeand times of others, while effectively making you a vital player in theteam.

All classes should begin with a class header comment, which is in thefollowing format/**

* The first sentence is used by Javadoc to make summary of this class.

* The first sentence should be crisp, brief and informative enough

* to stand on it's own. Follow the Javadoc @ tags to maximize your

* comments.

*

* @version $Revision$ $Date$

* @author Your name here* @see java.io.IOException

*/

Each class comment block must include

o Exactly one @version

o At least one @author

o Use of keywords $Revision$and $Date$to fill in @version tags isrecommended

o @see or {@link..} for every non trivial class referred to by this class.

Each method comments should include

o Purpose of the method

o Preconditions

o Effects

o Algorithmic notes

o Examples of usage

o @parambased description of all input parameters

o @returnbased description of the returned value

o @throwsbased description of all the exceptions

o @linkor @seebased reference to all the referred methods
mailto:%7B@linkmailto:%7B@linkmailto:%7B@link


9/17


JAVADOC style comments should not be used inside methods

C style (/*.*/) comments should be used for explaining logical block ofstatements. (Please be aware that having once documented a methodsalgorithm in the method comments, it may not be necessary to documentevery line of code in that method). Think and document complex blocks,which you think may be difficult for a new reader to comprehend. Avoidover documentation.

C++ style (// ..) comments should be used for briefly describing aparticular statement (preferably place the comment at the end of thestatement, in the same line).

Precede a comment line of any kind with a blank line. Immediately followup the comment line with the code block for which it is intended.

Take full advantage of JAVADOC and HTML tags to significantlyimprove the readability at HTML levels. Here are some of the HTML tags

you can use

o This is a bulleted lista bullet point

o - Emphasize as code

o - pre-format

o - boldify

o - italicize

6. Format

Following formatting rules should be obeyed Indentation consists of spaces only (in particular no tab characters

allowed).

80 column line is recommended

Statement spill over (in case the statement cannot fit in a single line)should be indented. The recommended indentation techniques are

o Begin at the same level where the right hand side of the previous statementbegan

o Or Indent one level in

o However only one of the above should be consistently used for a project.

Each indentation level is four spaces.

Method declarations are seperated from the comments of the followingmethod by exactly two lines of whitespaces.

Complex statements (if-else, for, while, etc.) should be fullyparenthesized, for readability and clarity. Statements with in complexexpressions should be indented one level more than the outer complexexpression.

No more that one simple statement should be put on a line.

Left-brace ("{") placement occurs at the end of the current line of code in

all cases. Code follows on the next line, indented by a single indentation


10/17


spaces. Right-closing-brace (}) placement occurs in a new line. Exampledisplays the various related situations /**

* Class below

*/

public class Junk {

/*

* Method here

*/

public void foo(ParameterType paramType) {

if (condition) {

}else {

}

for (int i = 0; i < loopLimit; i++) {

}

}

}

For all paired statements like try-catch, if-else, do-while etc. the secondpart of the statement should begin on the same line as the closing brace ofthe first.try {

/* Block comment */

} catch (MyException e) {

/* TODO */

}

All binary operations (except .) (+, /, *, etc.) and assignments should bebuffered by a single space. Unary operations (like -, !, and ++) should notbe separated by their operands. For example:double x =(y +z);

x++;

Brackets should always be used for conditionals and loops (even if thereis a single statement within). For example:

if (condition) {a = b + c;

}

A keyword followed by a parenthesis should be separated by a singleblank space. For example:if (condition) {

A blank space should not be used between a method name and itsopening parenthesis for the parameters. For example:public void foo(int b, int c) {

m_a = b + c;

}

Within parenthesis arguments, or expressions should have a blank spaceafter the delimiter. For example:public void foo(int b, int[] c) {

for (int i = 0; i< c.length; i++) {

...

}

}

It is recommended to have application-logging statements indented at thesame level as method declarations. For example:public class Junk {

public void foo(int b, int c) {

if (condition) {

a = b + c;

logger.debug();

}

}

}


11/17


7. Layout The header as described above should immediately be followed by the

package statement

Import statements should follow the package statement. Importstatements should be ordered according to following rules

1. Core imports of the form "import java." are listed first;

imports of standard Java extensions of the form "importjavax." are listed next; and all remaining imports follow.

2. Import lists (core, extension and other) are sorted in alphabetic orderindependently.

3. Avoid import lines which use the '*' construct(like "import java.io.*").Using this construct makes it difficult to determine exactly which classes arereferenced by your class without detailed inspection of the code.

Public Class level variables should be declared first with in a class(usually public static finals), followed by public Class level methods(public statics), followed by public instance methods (grouped byfunctionality), followed by protected instance methods, followed bypackage instance methods, followed by private instance methods,followed by protected instance variables, followed by package instancevariables, followed by private instance variables.

8. Best Practices (JSP/ Servlet/ EJB inclusive)! It is recommended to visit the design once again and resort to refactoring

of a class in case the lines of code in a class goes beyond 1500 lines (inclusiveof comments).

Rationale: It is very likely that you have grouped logically separablefunctionalities together.

! Justify declaration of protected and package variables/methods

Rationale: Protected variables/methods should be used only after makingsure that sub-classing and overriding will not be in any manner able tocompromise the robustness of other methods of the parent class that mightdepend on these methods. (If you use tools like JTest for static code analysis,it will point out such possible places to you and identify them as code-defects

by default)

! Avoid accessing class variables using instances

! Do not use deprecated API

! Use StringBufferrather than a Stringwherever a lot of modificationsare required (specially in a loop)

Rationale: String being an immutable object will lead to a lot of objectcreations.

! Change an object value to nullwhen that particular instance is notrequired any more


12/17


! Always use try-catch-finally, wherever a usage of releasable resources isinvolved. Release the resources in finally to ensure that even in exceptionalsituations resources will not be held up by the broken piece of code.

!Use application logging (use standards tools like Log4jor JSDK1.4standard logging mechanism), and log all milestones (information, error, and

debug related). Use lighter API to query about logging level wherever acostly object creation for logging is required.

! Avoid throwing and catching Base classes like Exception, rather throwand catchspecific exceptions.

! Use Interface based interactions between objects wherever possible, likeuse Collection rather than specific Vector for return in a method. This way theseam would still be valid if one of the objects changes that implementation ofthat interface (this will help in making the classes as independent as possible

from each other)! Declare variables final, if you do not intend to modify their values apart

from the declaration and definition time.

! Reap the benefits of Object Orientation wherever possible. For example:common functionality should be encapsulated either in interfaces (and animplementation factory written for them) or in inheritable base classes, whichcan be directly inherited.

! Encapsulate database interactions in DAO (Data Access Objects) or Entitybeans.

!

Keep the code complexity low, for example: keeping track of more than 4levels of nestings becomes difficult for a programmer. Sort to refactoringmethods if such becomes the case. A common indicator (if you are using the80 column restriction) is that the moment the code starts spilling over toomuch, the nesting has gone deep (and hence the complexity).

! Write automation test suites for unit testing (use of JUnit isrecommended). Write test case along with the code rather than as an afterexercise.

! It is recommended to override toString()method for ease in debugging

! It is also recommended to override equals()method appropriately in

case the objects are expected to participate a lot in sorting etc.

! Appropriately evaluate the tradeoffs while using Stateful session beans.They can be heavy on performance.

! When sensible, consider writing a mainfor the principal class in eachprogram file. The mainshould provide a simple unit test or demo.

Rationale: Forms a basis for testing. Also provides usage examples.

! For self-standing application programs, the class with mailshould beseparate from those containing normal classes.

Rationale: Hard-wiring an application program in one of its component classfiles hinders reuse


13/17


! If you can conceive of someone else implementing a class's functionalitydifferently, define an interface, not an abstract class. Generally, use abstractclasses only when they are partially abstract; i.e., they implement somefunctionality that must be shared across all subclasses.

Rationale: Interfaces are more flexible than abstract classes. They supportmultiple inheritance and can be used as mixins' in otherwise unrelatedclasses

! Consider whether any class should implement Cloneable and/orSerializable.

Rationale: These are magic interfaces in Java, that automatically addpossibly-needed functionality only if so requested.

! Declare a class as finalonly if it is a crucial class for the integrity of apackage and other classes in the package depend on its implementation.

! Never declare instance variables as public.

Rationale: The standard OO reasons. Making variables public gives upcontrol over internal class structure. Also, methods cannot assume thatvariables have valid values

! Minimize reliance on implicit initializers for instance variables (such asthe fact that reference variables are initialized to null).

Rationale: Minimizes initialization errors.

! Minimize statics (except for static final constants).

Rationale: Static variables act like globals in non-OO languages. They makemethods more context-dependent, hide possible side effects, sometimespresent synchronized access problems. and are the source of fragile, non-extensible constructions. Also, neither static variables nor methods areoverridable in any useful sense in subclasses.

! Generally prefer longto int, and double to float. But use int forcompatibility with standard Java constructs and classes (for the majorexample, array indexing, and all of the things this implies, for example aboutmaximum sizes of arrays, etc).

Rationale: Arithmetic overflow and underflow can be 4 billion times less

likely with longsthan int; similarly, fewer precision problems occur withdoubles than float. On the other hand, because of limitations in Java atomicityguarantees, use of longs and doubles must be synchronized in cases whereuse of intand floatsometimes would not be.

! Use final and/or comment conventions to indicate whether instancevariables that never have their values changed after construction are intendedto be constant (immutable) for the lifetime of the object (versus those that justso happen not to get assigned in a class, but could in a subclass).

Rationale: Access to immutable instance variables generally does not requireany synchronization control, but others generally do.

! Avoid unnecessary instance variable access and update methods. Writeget/set-style methods only when they are intrinsic aspects of functionality.


14/17


Rationale: Most instance variables in most classes must maintain values thatare dependent on those of other instance variables. Allowing them to be reador written in isolation makes it harder to ensure that consistent sets of valuesare always used.

! Minimize direct internal access to instance variables inside methods. Useprotected access and update methods instead (or sometimes publicones ifthey exist anyway).

Rationale: While inconvenient and sometimes overkill, this allows you tovary synchronization and notification policies associated with variable accessand change in the class and/or its subclasses, which is otherwise a seriousimpediment to extensiblity in concurrent OO programming. (Note: Thenaming conventions for instance variables serve as an annoying reminder ofsuch issues.)

!Avoid giving a variable the same name as one in a superclass.

Rationale: This leads to hiding of the parent variable.

! Prefer declaring arrays as Type[] arrayNamerather than Type arrayName[].

Rationale: The second form is just for incorrigible C prgrammers.

! Ensure that non-private statichave sensible values even if no instancesare ever created. (Similarly ensure that static methods can be executedsensibly.) Use static intitializers (static { ... } ) if necessary.

Rationale: You cannot assume that non-private statics will be accessed onlyafter instances are constructed.

! Write methods that only do one thing. In particular, separate outmethods that change object state from those that just relies upon it. For aclassic example in a Stack, prefer having two methods Object top() and voidremoveTop() versus the single method Object pop()that does both.

Rationale: This simplifies (sometimes, makes even possible) concurrencycontrol and subclass-based extensions.

! Define return types as voidunless they return results that are not (easily)accessible otherwise. (i.e., hardly ever write return this).

Rationale: While convenient, the resulting method cascades

(a.meth1().meth2().meth3()) can be the sources of synchronization problemsand other failed expectations about the states of target objects.

! Avoid overloading methods on argument type. (Overriding on arity isOK, as in having a one-argument version versus a two-argument version). Ifyou need to specialize behavior according to the class of an argument,consider instead choosing a general type for the nominal argument type(often Object) and using conditionals checking instanceof. Alternatives includetechniques such as double-dispatching, or often best, reformulating methods(and/or those of their arguments) to remove dependence on exact argumenttype.

Rationale: Java method resolution is static; based on the listed types, not theactual types of argument. This is compounded in the case of non-Object types


15/17


with coercion charts. In both cases, most programmers have not committedthe matching rules to memory. The results can be counterintuitive; thus thesource of subtle errors. For example, try to predict the output of this. Thencompile and run.

class Classifier {

String identify (Object x) { return "object"; }

String identify (Integer x) {return "integer"; }

}

class Relay {

String relay(Object obj) { return (new Classifier()).identify(obj); }

}

public class App {

public static void main(String[] args) {

Relay relayer = new Relay();

Integer i = new Integer(17);

System.out.println(relayer.relay(i));

}

}

JSP/Servlets:

! It is suggested to break JSPs per a bread-crumb model, where you break the viewinto header, footer, navigation, and content areas.

Rationale: This will help organize content better, as well as enforcing constraintslike security constraints in a more centralized manner.

! It is suggested to follow Model II (MVC) based design for you application webfront.

# So use JSPs only as views (aim at 0 javacode in JSPs). Populate dynamic datain JSPs using Form/Helper beans only.

#

Do not code business process driving directly in Servlet, rather usedependent Action classes, which capture the business process delegation, andhave an Action per business functionality to avoid complexity.

# Make the navigation configurable, preferably thru XML based configurationfiles, so that you can later plug and play navigation paths.

# Apache Jakarta Struts framework provides for all of these. It is recommendedto use it.

! Hide special scripting or constraint enforcement in tags.

! Create Abstract classes from which you derive the implementation of yourAction and Helper/Form bean classes.

Rationale: This way you wont have to duplicate the effort to introduce a genericlogging / error handling / validation / monitoring mechanism in allHelper/Form bean and Action classes

! As far as possible do not bank on passing parameters in the URL to Servlet/JSP.This may give a semantic clue to a hacker to get the data out of the portalbypassing normal portal security. This would specially be true when security isbeing applied at the level of display of options themselves rather than at thesubmission level also. By looking at a URL and the parameters to submit, theauthentic users of the portal specially, may be able to gain unauthorised access.Hence the URL submits should only have reference to the user session id and theindexes, which in that user session point to corresponding semantic entitiy.


16/17


! Do not use hidden parameters. A smart hacker may get a lot of details by doing aview page source on the browser client. Such things should also be stored inthe session.

!Session id should have a component of randomness to it. It should not be anormal sequence number as then a smart internal hacker can guess the sequenceand try unauthorised access.

! For JSPs it is recommended to use a nesting level of 2 spaces (rather than 4, asrecommended for general Java)

9. AMENDMENT HISTORY

Version Date Add it ions/Modif icat ions Prepared/

Revised by

1.5 29thJune2005

Reformatting minor changes NamitaSehgal

1.4 9thJuly04

Reformatting minor changes NamitaSehgal

1.3 14thMar03

Copyright messages not to beincluded in Header and Footer

Kiran Bellary

1.2 21stAug02

Section7 and 8. Java GUI and Serverside changes.

Kiran Bellary

1.1 11thAug00

Section 7.1-7.4, and 9-15 added RahulBhattacharya

1.0 23rdJun97

First Release Ashish Gupta

PEROT SYSTEMS and the PEROTSYSTEMS logo aretrademarks of Perot Systems and may be registered orunregistered in the United States, the EU, and othercountries. All other trademarks are the property oftheir respective owners.


17/17


java standards

Documents