Appendix F

<<<<<<< HEAD Appendix F

Lexical Systems Group, Java Coding Standard

NLM/NIH

(Draft)

Version Number: 1.0

Last Updated 05/17/00

Table of Contents

1. Introduction 3

1.1 Rational 3

1.2 Scope 4

2. General Mandate & Guidelines 5

2.1 Code Layout 5

2.2 Comments 7

2.2.1 General Commenting Guidelines 8

2.2.2 File Prolog & Comments 8

2.3 Declarations 9

2.3.1 Variables 9

2.3.2 Methods 9

2.3.3 Classes 9

2.4 Flow Control 10

3. Naming Conventions 12

3.1 General 12

3.2 Directories 12

3.3 Packages 13

3.4 Files 13

3.5 Classes 13

3.6 Methods 14

3.7 Variables & Parameters 15

3.8 Class Data Members 15

3.9 Constants 16

4. File & Class Prolog 16

4.1 Standard File Prolog 16

4.2 Java file Prolog Sample 17

4.3 Java Class Prolog Sample 17

4.4 Descriptions 17

APPENDIX A - Illustration of Lexical Systems Group Java Standard Coding Style 19

APPENDIX B - Abbreviation of Naming convention Style1

1. Introduction

Think about musicians. There are only eight notes in the scale - no more, no less. In addition, notes within a scale can only be combined in certain ways. Most random combinations of notes or rhythms are mere discordant noise rather than music.

Thus, in order to produce music, a musician must follow a very constrained form. Has this led to any lack of music? Absolutely not. Following this constrained form, and working within its limitations, has allowed musicians to create everything from subtle tribal rhythms to classical music to rock and roll, and every other type of music you can mention.

Thus, instead of limiting musical expression, accepting a constraining form and working within its limits has had the exact opposite effect by allowing musicians the freedom to create without worrying about extraneous details. As long as a musician stays within the constraints, he or she doesn't have to worry about whether or not some combination is music or noise. By staying within a framework of what is accepted as music, musicians can concentrate instead on their art. That is, by accepting the framework as a starting point, musicians can quit thinking about the framework and concentrate instead on what they are trying to express.

The exact same concept applies to software development. Writing code within a constrained style standard frees the developer from having to decide again and again how the code should look on the page, and allows him or her to concentrate instead on the code itself. That is, by accepting the style as a starting point, the developer can quit thinking about style issues and concentrate instead on what he or she is trying to express.

1-1. Rationale

"Remember, a primary aim of writing code is to make its meaning clear to the next person reading it - and that person just might be yourself a few years hence." Stroustrup, The C++ Programming Language, Third Edition, pp. 508.

All code must either evolve or die. If you want your code to survive and be useful, then you must follow a clear and consistent style/standard so that your code can evolve gracefully.

Following a clear and consistent style helps ensure that code is easier to read. Code that is easier to read is easier to understand and maintain. Code that is easier to understand and easier to maintain is code that will be better able to withstand the stress of evolution.

Code that is messy in appearance or difficult to read is not good code. And it may very well be the code that comes back to haunt you over and over again like a recurring nightmare.

If you fail to follow a clear and consistent style/standard, then you will inevitably end up with a coding mess that no one else can understand. This code will be shoved off into a corner where no one else has to deal with it, and you will be stuck with handling the mess every time it needs to be modified. Some may mistakenly think of this as job security, but in reality it is only lack of professionalism. If your code is clear, clean and easy to work with, then you can share the work of evolving it with others. Your time will be freed to write more clear, clean, easy to work with code, instead of being stuck forever with the same old ugly mess in front of you. Take the time now to think seriously about what's really in your best interest, to say nothing about your professional obligations to your coworkers and employer.

Good code, code that is clear, clean and easy to understand, is in everybody's best interest, and is the only product that is appropriate for professional developers. Producing good code allows you to take pride and enjoyment in your work, and should always be your primary goal.

In order to meet a primary goal, we sometimes must sacrifice lesser goals. For instance, each of us has our own ideas about how our code should look. However, if every developer follows his or her own individual style/standard, no matter how perfect it may be, the development team as a whole loses the benefit of having all code written in a single, clear, consistent style/standard.

Getting group agreement on a coding style/standard is never easy. In fact, it is one of the more difficult tasks in software development. This is so because writing code is still, for all the science that may be involved, very much an art produced by individuals. Each developer may feel handicapped by having to follow a style/standard that is not his or her own, but we must all accept the fact that we work on a team. Sometimes this means we have to do what is best for the team, rather than what we might individually prefer. Professionals accept this fact and deal with it.

There is a popular engineering proverb that says "Form is liberating". Truer words were never spoken. Do not fall into the trap of confusing chaos or anarchy with freedom of expression.

1-2. Scope

This document specifies the Java coding style/standards to be used for all developed, deliverable code on the NIH/NLM Lexical Systems Group projects. It does not apply to non-deliverable code such as test drivers, but it is highly recommended that these standards be followed for all developed Lexical Systems Group code.

This document includes "Java language Standards" (hereafter referred to as "standards"), "programming rules", and "style rules". "Java language standards" are specifically language-oriented (for example, "goto prohibited"); programming rules" mandate how certain language constructs are used (for example, naming conventions); and "style rules" pertain to the formatting of the code (for example, indentation). Within each category, there are mandatory and guideline components. Mandatory items cannot be violated (i.e., violation of a mandatory item results in automatic rejection of the software turnover); guidelines may be violated under a written approved waiver by a project technical leader.

A formal waiver process is in place and may be used when circumstance dictate, but is strongly discouraged. Any standard or rule in this document may be violated if an appropriate waiver is approved.

2. General Mandate & Guidelines

It is the responsibility of all Lexical Systems Group projects developers to know and apply this Java Style Standard to their own work. Code that does not conform to this standard shall not be reviewed. If a review is scheduled and it is determined that the code does not conform to this standard, then the review shall be postponed until the code is in conformance. The intent of this rule is to avoid wasting time in review sessions debating style issues. This will allow the review process to concentrate on the code instead.

2.1 Code Layout

The layout of code on the page shall reflect the structure of the code. Just as that structure should be clean, elegant and simple, the layout of the code on the page should be clear and easy to read.

Guideline: Make sure the layout of the code is clear and easy to read.

Mandatory: None.

Indentation is important to indicate the structure of the code. In order to preserve indentation levels, always use spaces to indent. Never use tabs. Spaces appear the same, i.e., give the same indentation, in all editors and on all printers, thus giving the code the same appearance on the page regardless of who is looking at it. Tabs, on the other hand, expand differently depending on editor or printer settings. Use four spaces as your indentation level. Less is not easy to see, and more causes deeply indented code to run off the right side of the page.

Guideline: None.

Mandatory: Use 4 space as an indentation level.

For the same reason, always use a fixed-width font (like Courier) and never use a proportional-width font (like Times New Roman). This too will guarantee that everyone who sees the code will see the same layout on the page. And since that layout reflects the structure of the code, following this guideline will ensure that the same structure is equally visible to everyone who looks at the code.

Guideline: Use Courier font.

Mandatory: Use a fixed-width font.

If you use spaces as your indentation level and code still runs off the right side of the page, then you almost certainly have other problems. Any code that is indented deeper than four or five levels is extremely difficult to understand. You may, on very rare occasions, have code indented more deeply than this, but such an occurrence should always be viewed with suspicion (Provided an written approved waiver). You can generally get around this problem by breaking out some of the more deeply indented code into separate methods.

Guideline: Don't use indentation deeper than 4 levels.

Mandatory: None.

Do not put multiple statements on a single line. Although Java allows this, but it only makes the code harder to read. The only exception shall be for assignment of a single value to multiple variables of the same type. For example: A = B = C = 0; where A, B and C are all of the same data type.

Guideline: None.

Mandatory: Multiple statements on a single line are prohibited.

The maximum length of a source line shall be 79 characters, so that each individual line will fit on a single line without wrapping. Exceptions are allowed for strings in double quotes such as HTML statements, debugging messages, database queries, etc.

Guideline: None.

Mandatory: 79 character or less for the length of lines.

Order declarations with initialized variables first. Leave one indentation level between type names and variable names. Align variable names, = signs and values in columns.

Guideline: Align variable names, = signs, and values in columns.

Mandatory: Order declarations with initialized variables first.

The following is an example of good layout:

public class Retirement

{

Public static void main(String[] args)

{

double ballance = 0;

int years = 0;

double goal;

double interest;

double payment;

// read in goal and payment information

goal = Concole.readDouble

("How much money do you need to retire?");

payment = Console.readDouble

("Interest rate in % (ex:use 7.5 for 7.5%);")/100;

while(balance < goal)

{

balance = (balance + payment) * (1 + interest);

years++;

}

System.out.println("You can retire in " + years + "years.");

}

The following is an example of bogus layout:

public class Retirement

{

Public static void main(String[] args)

{

double ballance = 0;

int years = 0;

double goal;

double interest;

double payment;

goal = Concole.readDouble

("How much money do you need to retire?");

payment = Console.redDouble

("Interest rate in % (ex:use 7.5 for 7.5%);")/100;

// read in goal and

//payment information

while(balance < goal)

{

balance = (balance + payment) * (1 + interest);

years++;

}

System.out.println("You can retire in " + years + "years.");

}

2.2 Comments

The importance of comments cannot be emphasized enough. Every file should have an introductory section that summarizes the contents of the file (prolog). Every class definition and method should have an introduction. Within each function, all non-obvious variable declarations should be commented. Every logical section of the method (function) should be separated and commented, as needed.

Comments are mandatory for:

Variable declaration statements,

"Fall through" in switch and if statement,

Operating system specific commands or calls,

File and class specific prolog,

Operations on byte or bit ordering.

2.2.1 General Commenting Guidelines

Use // commenting style when programming In Java, not the /* */ style. However, in those cases where it is not desirable to comment out the remainder of the line, use of comments, /* */, is acceptable.

Make sure comments and code agree. When you are modifying code, modify the comments.

Don't just echo the code with comments - make every comment count. Below is an example of an useless comment.

++i; // increment i

Don't comment bad code - rewrite it.

Use /** */ commenting style for the file prolog to generate documentation automatically.

Use // or /** */ commenting style for the class prolog.

2.2.2 File & Class Prolog Comments

Each class declaration (e.g., in a prolog) shall be preceded by a brief comment describing the intended use of the class. This comment also shall specifically include any special information about limitations on, or assumptions.

Anything that can be enforced by the compiler shall be so enforced rather than relying on a comment. For example, suppose that the destructor for a class is only to be invoked by another member function under a certain condition. The condition cannot be enforced by the compiler, but by making the destructor private we can at least ensure that no one outside the class can use it inadvertently.

There are certain information that should be put into file prolog comments in source files.

The file prolog is intended to be read by users and maintainers of the code. The file prolog should be related to proper usage, i.e., how the class should be used, what conditions the class assumes, and what limitations may apply to its use. That is, as per the previous code sample. In additional, coding notes should be provided. For example, prolog might indicate why a particular algorithm was chosen, and what conditions might lead to another algorithm as a better choice. This is also a good place to note the evolution originally envisioned for the code, i.e., if enhancements are planned for later, noting them directly with the code to be enhanced ensures that the code and the plan are at least in close physical proximity.

2.3 Declarations

2.3.1 Variables

Declare variables where they are needed. In Java you do not have to declare all variables used in a method at the start of that method. If you wait and declare the variable later, where it is needed, which will probably be right before the variable's first use, then you are more likely to be able to assign it an appropriate initial value. You can also declare variables inside the braces of a loop or conditional to limit their scope to the enclosing braces. This can be much less expensive than initializing variables that are never used because the code path to their use is not executed in a particular run. It also prevents misuse or confusion of variables intended for only a small scope. In addition, this will make software maintenance much easier. For instance, developer will maintain only the specific block when there is a change, (such as duplication and deletion) without worry about modify variables in several different places.

Use keyword final for constant variables wherever possible.

Each variable must be declared upon a separate line.

2.3.2 Methods

For each method there shall be an explicit prototype giving the return value type, parameter types and meaningful parameter names. If the method is local to a single source file, then it shall be declared in that file and shall be explicitly qualified as private.

2.3.3 Classes

For class declarations, always put the public declarations first. This is the only part that you really want users of the class to see, so put it where they are sure to notice, and make it easy for them to read without having to wade through declarations they don't really need to know about.

class Good

{

constants

constructors()

public methods()

protected methods()

package scope methods () //default

private methods()

Instance variables

Static variables

};

In general, one class per implementation file is a good idea. However, there are sometimes cases where nested classes or closely cooperating classes should be in the same file. Such as in GUI design, we may put all classes of one window in one file. Thus, one class per file is not mandated as a standard, but it is suggested as a strong guideline. Deviations from this guideline shall be evaluated on a case-by-case basis and this guideline shall be ignored only with good cause.

2.4 Flow Control

Always provide a break or return statement for each case in a switch statement. In those very rare cases where it is desired to fall through from one case to another, explicitly comment that the break statement was deliberately left out and why.

Always provide a default case in switch statements. You may never expect this code to execute, in which case (no pun intended) this would be a good place to catch an error. Or there may be some suitable default action you can take. In either case, always having an explicit default action clearly expresses your intent, and prevents code from just falling out of the switch statement in an unknown state.

Switch(value)

{

case LIVE:

SomeFunc(); // Bogus: falls into next case

case DIE:

AnotherFunc();

break; // Good

case BREATHE:

YetAnotherFunc();

// Fall into next case // OK: explicit comment

case COUGH:

SomeFunc();

break;

default: // Good: default is required

HandleError();

break;

}

If you have a sequence of if ... else if ... else statements, and you always expect at least one of the if conditions to be true, make this explicit in your code by putting a catchall else as the last statement. This makes a fine place to put in error code when this condition is detected.

// Bad way

if(count > 0)

{

amount = FigureAmount(count);

}

else if(count < 0)

{

amount = SpecialCase(count);

}

long average = amount/count; // What if count == 0?

// Better way

if(count > 0)

{

amount = FigureAmount(count);

}

else if(count < 0)

{

amount = SpecialCase(count);

}

else

{

// count cannot be zero

Error();

return; // not recommanded

}

long average = amount/count; // OK, can't get here if count is zero.

Avoid to put "return" inside a control flow. It will be a more consistent layout if all the return are put at the very end of the method. This should be used as a guideline.

Always use braces { } to delimit compound statements, even if there is only a single statement in the compound statement. For example:

if(condition)

{

single-line action;

}

Consistently following this guideline will prevent the common mistake of adding an additional statement to the single-line action, at the same indentation level, and expecting it to be part of the compound statement. That is:

if( transferApproved )

CreditAccount( acct1, amount );

is likely to evolve into the coding error:

if( transferApproved )

CeditAccount( acct1, amount );

DebitAccount( acct2, amount ); // NOT part of compound statement!

Whereas, the more clearly coded:

if( transferApproved )

{

CreditAccount( acct1, amount );

}

is much more likely to evolve into the correctly coded:

if( transferApproved )

{

CreditAccount( acct1, amount );

DebitAccount( acct2, amount );

}

If a flow construct does the processing inside the condition, provide empty braces with an explicit comment.

while(index++ != 0); // Bad

while(index++ != 0) // Good

{

// Intentionally empty block

}

Always use parentheses to clarify the order of complex expressions. Remember that your readers are humans, not compilers.

if(a < b < c) // Huh? Is ((a < b) < c)

if(a & b < 8) // What? Is (a & (b < 8))

3. Naming Conventions

3.1 General

Everything that has a name shall have a meaningful name. If you cannot come up with a good, meaningful name for something, then you do not yet understand what that something is. More importantly, if you have a problem coming up with a good, meaningful name for something, then you have a problem that needs to be solved before you can progress.

Leading underscores ('_' shall not be used. Names with a single leading underscore are reserved for C language implementers (compiler vendors), and names beginning with a double underscore are reserved for C++ implementers. I don't know if this style is reserved by Java. However, we should not use this style.

Name must begin with a letter.

All naming conventions are mandatory.

Name must be 31 alphanumeric or underscore characters or less.

3.2 Directories

The name of an implementation directory shall accurately reflect the category of its contained files. The distribution of directories should be mapped into the software architecture design. UL styles (see Appendix B for details) is used for the directory naming convention.

3.3 Packages

The name of a Java package shall accurately reflect the characteristic of its category. In general, the name of a Java package should be the same as the name of its directory. Accordingly, Java source codes of different packages should not locate under a same directory.

3.4 Files

The format for Java source file name is as follows:

where

<ClassName> is the same as the name of the first class contained in the file. and

<extension> is ".java"

The name of an implementation Java file shall accurately reflect the contents of the file. In the case of a class, this means that the file name should reflect (the same as) the name of the class. The specific file naming rules are therefore:

The primarily public class name shall also be used as the file name (otherwise, Java compiler will catch it). The names of inner classes or package class can be different from the file name (refer to section 2.3.3).

3.5 Classes

The first letter of any name declared in a class declaration shall be capitalized. If such a name consists of multiple words, then each word shall begin with a capital letter and shall not be separated by an underscore character (UL)

Examples of good names:

class MyClass

{

...

};

Examples of bad names:

class Bad_Class // underscore

{

...

};

A good convention is that a class name should be a noun (Order) or a noun preceded by adjective(RushOrder) or a gerund (an "ing" word - BillingAddress).

The developer must ensure that there is no more than one class with the identical name.

3.6 Methods

The first letter of a method name shall be capitalized. If such a name consists of multiple words, then each word shall begin with a capital letter and shall not be separated by an underscore character (UL). (Yes, this makes function names and class names look very similar, but there is no possibility of confusion due to the very different contexts in which these names are used).

Examples of good names:

double GetBonus(int performanceRating);

void Meditate(int listOfProblems);

Examples of bad names:

double getBonus(int performanceRating); // lower case

double Get_Bonus(int performanceRating); // underscore

double get_bonus(int performanceRating); // lower case and

// underscore

The naming convention of Java inner class should be treated the same as methods (not class).

The return type of each method must be explicitly defined. Use of type "void" for methods with empty argument lists and methods that do not return a value is mandatory.

With such convention, developer are able to distinguish methods from users' and Java's.

3.7 Variables & Parameters

Variables & parameters names shall begin with a lowercase letter. If such a name consists of multiple words, then each word after the first shall begin with a capital letter and shall not be separated by an underscore character (LUL)

Examples of good names:

long amount; // variable

int GetNextValue(int curIndex, int restart); // params

Examples of bad names:

long Amount; // upper case

int GetNextValue(int cur_Index); // underscore in param

The size of every array shall be given as a named constant. When declaring a character array intended to contain null-terminated strings, use this constant plus one to allow for the null-terminator. Never use a hard-coded "magic number" to determine the size of any array.

char[] nameBuffer = new char[MAX_NANE_SIZE]; // Bad. Forgot

// space for null

// terminator.

char[] nameBuffer = new char[MAX_NAME_SIZE + 1]; // Good!

char[] nameBuffer = new char[10]; // Magic number Bogus

Global variables should not be used as a guideline for object-oriented design.

3.8 Class Data Members

Class data member names shall begin with a lowercase letter and shall end with a trailing underscore character (LUL_). If such a name consists of multiple words, then each word after the first shall begin with a capital letter and shall not be separated by an underscore character.

Examples of good names:

long face_;

short attentionSpan_;

Examples of bad names:

long face; // no trailing underscore

short attention_Span_; // words separated by an underscore

With such a convention, developers are able to distinguish from data members and local variables.

3.9 Constants

There is no key word for constants in Java. However, constant may be implemented by using keyword "final". Constant names shall be all capitals. If such a name consists of multiple words, then the words shall be separated by an underscore.

Examples of good names:

final int MODEL 911

final int MAX_SPEED 55

Examples of bad names:

final int model 911 // lower case

final int MaxSpeed 55 // mixed case and no underscore

Hard-coding of constants within a class, including character constants, is prohibited except for:

-1 and 1 to increment and decrement loop counters,

0 (zero) , and

string constants such as "\n", "\t", etc..

4. File & class Prolog

4.1 Standard File prolog

Every Java source file shall begin with a standard file prolog of the form delineated below. The prolog shown here is available. This file may be copied or read into your editor of choice so that you never have to type the standard boilerplate text and can just fill in the details needed.

4.2 Java file prolog sample

/************************************************************

* File: Template

* Author: Lexical Systems Group Developer

* Description:

* History:

* 01/01/00, [name], Initial creation

* Notes:

* Waivers:

**************************************************************/

4.3 Java class prolog sample

//--------------------------------------------------------------

// create a new class for ...

//--------------------------------------------------------------

4.4 Descriptions

Certain information should be provided in the file prolog. They are detailed as follows:

File: Name of the file. It should be the same as the very first class in the file.

Author: Java Source code developer (including designer and implementer).

Description: Entry shall contain sufficient information to enable an user of the code to use the code correctly and shall include any special information needed by someone expected to maintain the implementation. Items specifically noted shall include, but not be limited to:

Intended usage and purpose.

Known weaknesses, limitations, or potential problems.

Restrictions on the class and input calling parameters and return parameter.

Assumptions made by the code, for example, about input parameters or use of return values.

History: A list of changes made to the file, including a modification ID (if we use SCRT for tracking our defects, the SCRT ID should be filled in here), the developer's name, the date upon which the modification was made, and a brief description of the change. The first (earliest) entry should be for the initial release of the function; If this is software which had been "reused" from another source, the initial release information should be identify the original source.

Notes: Any additional detail of particular interest. This could include planned future enhancements or fine detail about the function's internal workings.

Waivers: Document all authorized waivers to the Lexical Systems Group Java Coding Standards that apply to this file.

Appendix A - Illustration of Lexical Systems Group Java Standard Coding Style

The standard coding style that shall be followed in all development at Lexical Systems Group is what is known in the literature as the extended style. This is a widely used style that is easy to follow and easy to read. Following is a brief, generic sample illustrating the appearance of the extended style as applied to each type of control flow structure.

Public static main(String[] args)

{

// Order declarations with initialized variables first.

// Leave one indentation level between type names and variable names.

// Align variable names, = signs and values in columns.

T var1 = value1;

T var2 = vale2;

T var3;

// note blank line separating declarations from code

if(condition1)

{

T var4 = value; // very local variable

condition1 true action;

}

else if(conditionN)

{

conditionN true action;

}

else // all conditions false

{

conditions false action;

}

// note blank line separating independent code blocks

for(init; condition; increment/decrement)

{

body;

}

while(condition)

{

body;

}

switch(constant expression)

{

// note blank line between each case

case value1:

action1;

break;

case valueN:

actionN;

break;

default:

default action;

break;

}

Notice how clean this sample appears on the page. An opening brace on a line by itself provides a clear visual demarcation between the condition test and the code being executed. Having both braces aligned at the same indentation level makes it very easy to see the limits of the enclosed code, and to spot missing braces. A blank line separating independent blocks of code makes them visually independent too.

Appendix B - Abbreviation of Naming Convention Style

UU: Names are all capitals. If such a name consists of multiple words, then the words shall be separated by an underscore. UU is used in constant names (declaring by keyword "final"). Example: MAGIC_NUMBER

LL: Names are all lower cases. If such a name consists of multiple words, then the words shall be separated by an underscore. LL is used for application directory name Example: lvg_tables. This style is not currently used in Lexical Systems Group Java Standard.

UL: The first letter shall be capitalized. If such a name consists of multiple words, then each word shall begin with a capital letter and shall not be separated by an underscore character UL is used for directory name, Java package name, file name, class names, and method names. Example: MyDirectory, MyPackage, MyFile, MyClass, MyMethod.

LUL: Names begin with a lowercase letter. If such a name consists of multiple words, then each word after the first shall begin with a capital letter and shall not be separated by an underscore character. LUL is used in variables and parameters names. Examples: localVariable.

LUL_: Names begin with a lowercase letter and shall end with a trailing underscore character. If such a name consists of multiple words, then each word after the first shall begin with a capital letter and shall not be separated by an underscore character. LUL_ is used in data member. Example: dataMember_.

======= Appendix F

Lexical Systems Group, Java Coding Standard

NLM/NIH

(Draft)

Version Number: 1.0

Last Updated 05/17/00

Table of Contents

1. Introduction 3

1.1 Rational 3

1.2 Scope 4

2. General Mandate & Guidelines 5

2.1 Code Layout 5

2.2 Comments 7

2.2.1 General Commenting Guidelines 8

2.2.2 File Prolog & Comments 8

2.3 Declarations 9

2.3.1 Variables 9

2.3.2 Methods 9

2.3.3 Classes 9

Thus, instead of limiting musical expression, accepting a constraining form and working within its limits has had the exact opposite effect by allowing musicians the freedom to create without worrying about extraneous details. As long as a musician stays within the constraints, he or she doesn�t have to worry about whether or not some combination is music or noise. By staying within a framework of what is accepted as music, musicians can concentrate instead on their art. That is, by accepting the framework as a starting point, musicians can quit thinking about the framework and concentrate instead on what they are trying to express.

1-1. Rationale

All code must either evolve or die. If you want your code to survive and be useful, then you must follow a clear and consistent style/standard so that your code can evolve gracefully.

Code that is messy in appearance or difficult to read is not good code. And it may very well be the code that comes back to haunt you over and over again like a recurring nightmare.

If you fail to follow a clear and consistent style/standard, then you will inevitably end up with a coding mess that no one else can understand. This code will be shoved off into a corner where no one else has to deal with it, and you will be stuck with handling the mess every time it needs to be modified. Some may mistakenly think of this as job security, but in reality it is only lack of professionalism. If your code is clear, clean and easy to work with, then you can share the work of evolving it with others. Your time will be freed to write more clear, clean, easy to work with code, instead of being stuck forever with the same old ugly mess in front of you. Take the time now to think seriously about what�s really in your best interest, to say nothing about your professional obligations to your coworkers and employer.

Good code, code that is clear, clean and easy to understand, is in everybody�s best interest, and is the only product that is appropriate for professional developers. Producing good code allows you to take pride and enjoyment in your work, and should always be your primary goal.

There is a popular engineering proverb that says "Form is liberating". Truer words were never spoken. Do not fall into the trap of confusing chaos or anarchy with freedom of expression.

1-2. Scope

A formal waiver process is in place and may be used when circumstance dictate, but is strongly discouraged. Any standard or rule in this document may be violated if an appropriate waiver is approved.

2. General Mandate & Guidelines

2.1 Code Layout

Guideline: Make sure the layout of the code is clear and easy to read.

Mandatory: None.

Indentation is important to indicate the structure of the code. In order to preserve indentation levels, always use spaces to indent. Never use tabs. Spaces appear the same, i.e., give the same indentation, in all editors and on all printers, thus giving the code the same appearance on the page regardless of who is looking at it. Tabs, on the other hand, expand differently depending on editor or printer settings. Use four spaces as your indentation level. Less is not easy to see, and more causes deeply indented code to run off the right side of the page.

Guideline: None.

Mandatory: Use 4 space as an indentation level.

For the same reason, always use a fixed-width font (like Courier) and never use a proportional-width font (like Times New Roman). This too will guarantee that everyone who sees the code will see the same layout on the page. And since that layout reflects the structure of the code, following this guideline will ensure that the same structure is equally visible to everyone who looks at the code.

Guideline: Use Courier font.

Mandatory: Use a fixed-width font.

If you use spaces as your indentation level and code still runs off the right side of the page, then you almost certainly have other problems. Any code that is indented deeper than four or five levels is extremely difficult to understand. You may, on very rare occasions, have code indented more deeply than this, but such an occurrence should always be viewed with suspicion (Provided an written approved waiver). You can generally get around this problem by breaking out some of the more deeply indented code into separate methods.

Guideline: Don�t use indentation deeper than 4 levels.

Mandatory: None.

Do not put multiple statements on a single line. Although Java allows this, but it only makes the code harder to read. The only exception shall be for assignment of a single value to multiple variables of the same type. For example: A = B = C = 0; where A, B and C are all of the same data type.

Guideline: None.

Mandatory: Multiple statements on a single line are prohibited.

The maximum length of a source line shall be 79 characters, so that each individual line will fit on a single line without wrapping. Exceptions are allowed for strings in double quotes such as HTML statements, debugging messages, database queries, etc.

Guideline: None.

Mandatory: 79 character or less for the length of lines.

Order declarations with initialized variables first. Leave one indentation level between type names and variable names. Align variable names, = signs and values in columns.

Guideline: Align variable names, = signs, and values in columns.

Mandatory: Order declarations with initialized variables first.

The following is an example of good layout:

public class Retirement

{

Public static void main(String[] args)

{

double ballance = 0;

int years = 0;

double goal;

double interest;

double payment;

// read in goal and payment information

goal = Concole.readDouble

("How much money do you need to retire?");

payment = Console.readDouble

("Interest rate in % (ex:use 7.5 for 7.5%);")/100;

while(balance < goal)

{

balance = (balance + payment) * (1 + interest);

years++;

}

System.out.println("You can retire in " + years + "years.");

}

The following is an example of bogus layout:

public class Retirement

{

Public static void main(String[] args)

{

double ballance = 0;

int years = 0;

double goal;

double interest;

double payment;

goal = Concole.readDouble

("How much money do you need to retire?");

payment = Console.redDouble

("Interest rate in % (ex:use 7.5 for 7.5%);")/100;

// read in goal and

//payment information

while(balance < goal)

{

balance = (balance + payment) * (1 + interest);

years++;

}

System.out.println("You can retire in " + years + "years.");

}

2.2 Comments

Comments are mandatory for:

Variable declaration statements,

"Fall through" in switch and if statement,

Operating system specific commands or calls,

File and class specific prolog,

Operations on byte or bit ordering.

2.2.1 General Commenting Guidelines

Use // commenting style when programming In Java, not the /* */ style. However, in those cases where it is not desirable to comment out the remainder of the line, use of comments, /* */, is acceptable.

Make sure comments and code agree. When you are modifying code, modify the comments.

Don�t just echo the code with comments - make every comment count. Below is an example of an useless comment.

++i; // increment i

Don�t comment bad code - rewrite it.

Use /** */ commenting style for the file prolog to generate documentation automatically.

Use // or /** */ commenting style for the class prolog.

2.2.2 File & Class Prolog Comments

There are certain information that should be put into file prolog comments in source files.

2.3 Declarations

2.3.1 Variables

Declare variables where they are needed. In Java you do not have to declare all variables used in a method at the start of that method. If you wait and declare the variable later, where it is needed, which will probably be right before the variable�s first use, then you are more likely to be able to assign it an appropriate initial value. You can also declare variables inside the braces of a loop or conditional to limit their scope to the enclosing braces. This can be much less expensive than initializing variables that are never used because the code path to their use is not executed in a particular run. It also prevents misuse or confusion of variables intended for only a small scope. In addition, this will make software maintenance much easier. For instance, developer will maintain only the specific block when there is a change, (such as duplication and deletion) without worry about modify variables in several different places.

Use keyword final for constant variables wherever possible.

Each variable must be declared upon a separate line.

2.3.2 Methods

2.3.3 Classes

class Good

{

constants

constructors()

public methods()

protected methods()

package scope methods () //default

private methods()

Instance variables

Static variables

};

2.4 Flow Control

Switch(value)

{

case LIVE:

SomeFunc(); // Bogus: falls into next case

case DIE:

AnotherFunc();

break; // Good

case BREATHE:

YetAnotherFunc();

// Fall into next case // OK: explicit comment

case COUGH:

SomeFunc();

break;

default: // Good: default is required

HandleError();

break;

}

If you have a sequence of if � else if � else statements, and you always expect at least one of the if conditions to be true, make this explicit in your code by putting a catchall else as the last statement. This makes a fine place to put in error code when this condition is detected.

// Bad way

if(count > 0)

{

amount = FigureAmount(count);

}

else if(count < 0)

{

amount = SpecialCase(count);

}

long average = amount/count; // What if count == 0?

// Better way

if(count > 0)

{

amount = FigureAmount(count);

}

else if(count < 0)

{

amount = SpecialCase(count);

}

else

{

// count cannot be zero

Error();

return; // not recommanded

}

long average = amount/count; // OK, can�t get here if count is zero.

Avoid to put "return" inside a control flow. It will be a more consistent layout if all the return are put at the very end of the method. This should be used as a guideline.

Always use braces { } to delimit compound statements, even if there is only a single statement in the compound statement. For example:

if(condition)

{

single-line action;

}

if( transferApproved )

CreditAccount( acct1, amount );

is likely to evolve into the coding error:

if( transferApproved )

CeditAccount( acct1, amount );

DebitAccount( acct2, amount ); // NOT part of compound statement!

Whereas, the more clearly coded:

if( transferApproved )

{

CreditAccount( acct1, amount );

}

is much more likely to evolve into the correctly coded:

if( transferApproved )

{

CreditAccount( acct1, amount );

DebitAccount( acct2, amount );

}

If a flow construct does the processing inside the condition, provide empty braces with an explicit comment.

while(index++ != 0); // Bad

while(index++ != 0) // Good

{

// Intentionally empty block

}

Always use parentheses to clarify the order of complex expressions. Remember that your readers are humans, not compilers.

if(a < b < c) // Huh? Is ((a < b) < c)

if(a & b < 8) // What? Is (a & (b < 8))

3. Naming Conventions

3.1 General

Leading underscores (�_�) shall not be used. Names with a single leading underscore are reserved for C language implementers (compiler vendors), and names beginning with a double underscore are reserved for C++ implementers. I don�t know if this style is reserved by Java. However, we should not use this style.

Name must begin with a letter.

All naming conventions are mandatory.

Name must be 31 alphanumeric or underscore characters or less.

3.2 Directories

3.3 Packages

The name of a Java package shall accurately reflect the characteristic of its category. In general, the name of a Java package should be the same as the name of its directory. Accordingly, Java source codes of different packages should not locate under a same directory.

3.4 Files

The format for Java source file name is as follows:

where

<ClassName> is the same as the name of the first class contained in the file. and

<extension> is ".java"

The name of an implementation Java file shall accurately reflect the contents of the file. In the case of a class, this means that the file name should reflect (the same as) the name of the class. The specific file naming rules are therefore:

The primarily public class name shall also be used as the file name (otherwise, Java compiler will catch it). The names of inner classes or package class can be different from the file name (refer to section 2.3.3).

3.5 Classes

The first letter of any name declared in a class declaration shall be capitalized. If such a name consists of multiple words, then each word shall begin with a capital letter and shall not be separated by an underscore character (UL)

Examples of good names:

class MyClass

{

�

};

Examples of bad names:

class Bad_Class // underscore

{

�

};

A good convention is that a class name should be a noun (Order) or a noun preceded by adjective(RushOrder) or a gerund (an "ing" word - BillingAddress).

The developer must ensure that there is no more than one class with the identical name.

3.6 Methods

Examples of good names:

double GetBonus(int performanceRating);

void Meditate(int listOfProblems);

Examples of bad names:

double getBonus(int performanceRating); // lower case

double Get_Bonus(int performanceRating); // underscore

double get_bonus(int performanceRating); // lower case and

// underscore

The naming convention of Java inner class should be treated the same as methods (not class).

The return type of each method must be explicitly defined. Use of type "void" for methods with empty argument lists and methods that do not return a value is mandatory.

With such convention, developer are able to distinguish methods from users� and Java�s.

3.7 Variables & Parameters

Examples of good names:

long amount; // variable

int GetNextValue(int curIndex, int restart); // params

Examples of bad names:

long Amount; // upper case

int GetNextValue(int cur_Index); // underscore in param

The size of every array shall be given as a named constant. When declaring a character array intended to contain null-terminated strings, use this constant plus one to allow for the null-terminator. Never use a hard-coded "magic number" to determine the size of any array.

char[] nameBuffer = new char[MAX_NANE_SIZE]; // Bad. Forgot

// space for null

// terminator.

char[] nameBuffer = new char[MAX_NAME_SIZE + 1]; // Good!

char[] nameBuffer = new char[10]; // Magic number Bogus

Global variables should not be used as a guideline for object-oriented design.

3.8 Class Data Members

Examples of good names:

long face_;

short attentionSpan_;

Examples of bad names:

long face; // no trailing underscore

short attention_Span_; // words separated by an underscore

With such a convention, developers are able to distinguish from data members and local variables.

3.9 Constants

Examples of good names:

final int MODEL 911

final int MAX_SPEED 55

Examples of bad names:

final int model 911 // lower case

final int MaxSpeed 55 // mixed case and no underscore

Hard-coding of constants within a class, including character constants, is prohibited except for:

-1 and 1 to increment and decrement loop counters,

0 (zero) , and

string constants such as "\n", "\t", etc..

4. File & class Prolog

4.1 Standard File prolog

4.2 Java file prolog sample

/************************************************************

* File: Template

* Author: Lexical Systems Group Developer

* Description:

* History:

* 01/01/00, [name], Initial creation

* Notes:

* Waivers:

**************************************************************/

4.3 Java class prolog sample

//--------------------------------------------------------------

// create a new class for ...

//--------------------------------------------------------------

4.4 Descriptions

Certain information should be provided in the file prolog. They are detailed as follows:

File: Name of the file. It should be the same as the very first class in the file.

Author: Java Source code developer (including designer and implementer).

Description: Entry shall contain sufficient information to enable an user of the code to use the code correctly and shall include any special information needed by someone expected to maintain the implementation. Items specifically noted shall include, but not be limited to:

Intended usage and purpose.

Known weaknesses, limitations, or potential problems.

Restrictions on the class and input calling parameters and return parameter.

Assumptions made by the code, for example, about input parameters or use of return values.

History: A list of changes made to the file, including a modification ID (if we use SCRT for tracking our defects, the SCRT ID should be filled in here), the developer�s name, the date upon which the modification was made, and a brief description of the change. The first (earliest) entry should be for the initial release of the function; If this is software which had been "reused" from another source, the initial release information should be identify the original source.

Notes: Any additional detail of particular interest. This could include planned future enhancements or fine detail about the function�s internal workings.

Waivers: Document all authorized waivers to the Lexical Systems Group Java Coding Standards that apply to this file.

Appendix A - Illustration of Lexical Systems Group Java Standard Coding Style

Public static main(String[] args)

{

// Order declarations with initialized variables first.

// Leave one indentation level between type names and variable names.

// Align variable names, = signs and values in columns.

T var1 = value1;

T var2 = vale2;

T var3;

// note blank line separating declarations from code

if(condition1)

{

T var4 = value; // very local variable

condition1 true action;

}

else if(conditionN)

{

conditionN true action;

}

else // all conditions false

{

conditions false action;

}

// note blank line separating independent code blocks

for(init; condition; increment/decrement)

{

body;

}

while(condition)

{

body;

}

switch(constant expression)

{

// note blank line between each case

case value1:

action1;

break;

case valueN:

actionN;

break;

default:

default action;

break;

}

Appendix B - Abbreviation of Naming Convention Style

UU: Names are all capitals. If such a name consists of multiple words, then the words shall be separated by an underscore. UU is used in constant names (declaring by keyword "final"). Example: MAGIC_NUMBER

LL: Names are all lower cases. If such a name consists of multiple words, then the words shall be separated by an underscore. LL is used for application directory name Example: lvg_tables. This style is not currently used in Lexical Systems Group Java Standard.

UL: The first letter shall be capitalized. If such a name consists of multiple words, then each word shall begin with a capital letter and shall not be separated by an underscore character UL is used for directory name, Java package name, file name, class names, and method names. Example: MyDirectory, MyPackage, MyFile, MyClass, MyMethod.

LUL: Names begin with a lowercase letter. If such a name consists of multiple words, then each word after the first shall begin with a capital letter and shall not be separated by an underscore character. LUL is used in variables and parameters names. Examples: localVariable.

LUL_: Names begin with a lowercase letter and shall end with a trailing underscore character. If such a name consists of multiple words, then each word after the first shall begin with a capital letter and shall not be separated by an underscore character. LUL_ is used in data member. Example: dataMember_.

>>>>>>> 7865ccc0658d27ade1eaf4ec9938a516af1fa1f9