Coding Guidelines
	Java Coding Guidelines

Version 1.4 29/11/2007

Approval

Name	Signature

Revision History

Date	Comment	Author
2007-10-09	Initial draft.	Vladislav Nikitin
2007-10-10	Review and update.	Sergey Zenevich
2007-10-11	Small fixes.	Pavel Lebedev
2007-10-11	Small fixes.	Sergey Zenevich
2007-11-29	Small fixes.	Sergey Zenevich

Table of Contents

Coding Guidelines 1

Java Coding Guidelines 1

1

1. Introduction 5

1.1 Overview and Scope 5

1.2 Targeted Readers 5

1.3 Typographical Conventions 5

2. Naming conventions 6

2.1 Introduction 6

2.2 Abbreviations 6

2.3 Packages 7

2.4 Classes 7

2.5 Interfaces 8

2.6 Annotations 8

2.7 Exceptions 9

2.8 Enumerations 9

2.9 Fields 10

2.10 Static Fields 10

2.11 Parameters 10

2.12 Methods 11

2.13 Field Accessors (Java Bean properties) 11

2.14 Generics 12

2.15 Summary 12

3. Comments 14

3.1 Introduction 14

3.2 Class comments 14

3.3 Method comments 14

3.4 Inline comments 14

4. Code formatting 16

4.1 Indentation, spaces and braces 16

4.2 Separation of operators and punctuators 17

4.3 Line length 17

5. General style recommendations 18

5.1 Anonymous methods 18

6. References 19

7. Glossary 20

8. Appendices 21

1.Introduction

1.1Overview and Scope

This document presents Java version of coding guidelines that is obligatory for all Itransition software development processes.

All details about development for other platforms are placed in separate documents. Platform independent information (like scripts development, graphical resources development) is stored in separate document.

1.2Targeted Readers

Targeted readers for the document are all Itransition Java developers.

1.3Typographical Conventions

The following special typographical conventions are used within the document:

Font	Comment
Italic	Represents emphasis or a referenced material’s title.
Fixed width	Represents any source code fragments (like class, method or attribute names), file names, etc.

2.Naming conventions

2.1Introduction

A consistent naming pattern is one of the most important elements of predictability and discoverability in a managed source code. Widespread use and understanding of these naming guidelines should eliminate many of the most common user questions. This section provides naming guidelines for the different types of entities used.

All identifiers should be written using only proper English words. Avoid too sophisticated words. Do not misuse words. Try to find the simplest and most correct word. Usually you should write “Unique”, but not “Extraordinary”.

The major goal of all conventions is high level of code understandability and maintainability. If you feel that conventions violation can increase understandability in some particular case, you can do that. But think twice before.

Do not use language specific naming. Do not create language-specific method and parameters names, as in the following example:

void write(double doubleValue);

void writeDouble(double value);

Use instead:

void write(double value);

Avoid using names that duplicate commonly used Java packages and classes. For example, do not use any of the following names as a class name: Object, String or Exception. See Java API for a list of standard packages and classes.

It is not recommended to use the same packages and classes names, which are coming with frameworks and libraries, used in a project.

2.2Abbreviations

To avoid confusion and guarantee cross-language interoperation, follow these rules regarding the use of abbreviations:

• Do not use abbreviations or contractions as parts of identifier names. This rule strictly selects InternetAddress spelling instead of InetAddress, InternetAddr, InetAddr. This significantly simplifies development, code analysis and maintenance. However, you may use standard abbreviation, such as Id, a.e. UserId.

• Do not use acronyms that are not generally accepted in the computing field at all. If well-known acronym exists use it to replace lengthy phrase names. For example: XML, HTML, HTTP, FTP, DB, IO, and UI. Also some widespread file extensions can be used (for example, PDF, GIF, JPEG, BMP, TIFF). However avoid problem area specific acronyms like DM; use DocumentManagement instead.

• When using acronyms, use Pascal case or camel case for acronyms more than two characters long. For example, use HtmlButton or htmlButton. However, you should capitalize acronyms that consist of only two characters, such as java.io.IOException instead of java.io.IoException.

Do not use a Hungarian notation prefix anywhere.