Coding Standards

Recommended book:
“The Elements of Java Style” (Allan Vermeulen et al; Cambridge University Press, 2000; ISBN 0-521-77768-2)

Code convention recommendations by SUN:http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html

Coding Standards for Kuali:  Kuali Standards

Why do we need coding conventions?

Coding conventions are akin to best practices evolved over time by the practitioners of the given craft (coding). Sticking to certain standards ensures that one is programming for the fellow developer and not for the machine.
Here is why it is important to have (and adhere to) a coding convention:

• The original author, seldom, maintains the software through its lifetime.
• Over three quarters of the lifetime cost of a piece of software goes to maintenance

The cornerstone of coding best practices is – Documentation. It helps in maintaining the code. It is often said “if it is not worth documenting, it is not worth running” (Nagler, 1995).

COMMENTING STANDARDS:

Document by commenting classes, interfaces, member functions, and fields immediately before they are defined.

Block comments (/…/) :

They are used to describe of files, methods, data structures and algorithms. Block comments should be preceded by a blank line to set it apart from the rest of the code.

Short comment (/* … */):

Also called as single-line comments as these appear in single line and are indented to match the level of code that follows. For e.g.

Trailing comments:

These comments appear on the same line as the code, but should be shifted far enough to separate them from the code.

End-of-line comment (//):

Since these comments can comment an entire line or a partial line they are used to succinctly explain why and/or what is happening in a given line. Rarely they are used in consecutive lines.
Example:

Key points: –

(1) Update comments: Comments that are not updated lie and mislead.
(2) Mention why something is being done, not just what: the what part is secondary because its present right there as a fact. Not documenting the ‘why’ would lead to subjectivity and may compromise the purpose of having comments/documentation in the first place.

NAMING STANDARDS:

File names:

JAVA Naming conventions:

*Adheres to the general naming conventions for methods: Names representing methods must be verbs an and written in mixed case starting with lower case.

Key points

(1) Length: Have names that are under 16 characters in length
(2) Abbreviations: Use abbreviations sparingly: abbreviations do not augment readability. In some cases they might mislead and have a different interpretation altogether.

GENERAL STRUCTURE OF A JAVA FILE

Beginning comments

All source files should begin with a c-style comment that lists the class name, version information, date, and copyright notice:

Package and import statements

Here the sequence commonly followed is package and then import statements
Package java.awt;
Import java.awt.circle.ColorRed;

Class & interface declaration

The following sequence should be maintained in the class and interface declaration section:

• Class/interface documentation comment
• Class or interface statement
• Class (static) variables
• Instance variables
• Constructors
• Methods

Example follows.

PROGRAMMING CONVENTIONS:

Classes

Declare the fields and member functions of a class in the following order:

1. Private Class Variables
2. Constructors
3. Public member functions
4. Protected member functions
5. Private member functions

Statements:

Note the indentation of the enclosed statements.
(1) FOR -statements
A for statement should have the following form:

(2) Do-While Statement
A do-while statement should have the following form:

(3) While Statement
A while statement should have the following form:

(4) Switch Statement
Every switch statement should include a default case. A switch statement should have the following form:

(5) Try-catch Statements
A try-catch statement should have the following format:

Constants

Avoid using constants directly. One way to use constants is:

Numeric values such as -1, 0 and 1 are sometimes used directly as an exception to this rule.

Local variables

(1) Document the purpose of the variable preferably with an end-line comment

(2) Declare one local variable per line of code:
That also makes it possible to document the variable with an end line comment.

(3) Use local variables for one thing only:
Reusing local variables makes comprehension difficult and hence affects maintainability. Side effects may also include some unexpected behavior and bugs in the code. These costs far exceed the sole benefit of reuse: less memory is used.

(4) Declare local variables immediately before their use:
This technique has got its merits and demerits. While on one hand it facilitates maintenance and allows for efficient memory allocation, it also means more dispersed declarations throughout the body of the code.

(5) Initialize variables when they are declared.

(6) Avoid assigning values to several variables in the same line: Readability is affectd and so is the effectiveness of comments attached to these variables.
For e.g.
testClass.fchar = fooclass.lchar = ‘a’; // avoid

Member functions

Since member functions perform an activity it is a common practice to have the first letter of a member function a strong verb, e.g. openList(), closeAccount(), etc.

Visibility

• Public: Used when the member function cab be invoked by objects and functions outside the class in which member function is defined.
• Protected: when member function is required only by functions and object within its class hierarchy.
• Private: When a member function is only invoked by same class functions and/or same class objects.

Scott Ambler offers a simple rule of thumb: If member function doesn’t have to be public then make it protected, and if it doesn’t have to be protected then make it private.

OTHER GENERIC BEST PRACTICES:

Use whitespaces:

Whitespaces increase the readability of the code tremendously. Notice the example and see the big difference, whitespaces make to readability and subsequent quick comprehension, yourself.
E.g.1
(PREFERABLE)
iteration=1;
grandTotal=bill.total()+getAmountDue();
grandTotal= rebater.rebate(grandTotal,this);

(AVOIDABLE)
iteration = 1;
grandTotal = bill.total() + getAmountDue();
grandTotal = Rebater.rebate(grandTotal, this);

Follow thirty seconds rule:

If a fellow programmer is able to understand a member function (or get the working knowledge) by looking at it for around thirty seconds then the member function had indeed been very well written.
A way to check it is if a member function fits within a screen (its variable, but perhaps an decent benchmark) then perhaps its well written.

 

Indent your code:

When code spans multiple lines it is a good idea to indent the lines subsequent to the first one. This clearly indicates that all subsequent lines are part of the first one.

Always put down braces in pairs:

It’s a good practice to immediately have a closing brace when one puts down an opening brace. The code can be subsequently be written in the space between the two braces.

Indentation

Indentation is much more than a matter of style. Correct indentation helps in identifying control flow and blocks of code.
Example:

Flag issues/broken code

Use XXX in a comment to flag something that is bogus but works. Use FIXME to flag something that is bogus and broken.

Blank Lines

Blank lines improve readability by setting off sections of code that are logically related.

Use two blank lines:

1. between class and interface definitions and
2. between sections of a source file.

Use one blank line between:

1. methods,
2. logical sections within a method.

Blank Spaces

(1) A keyword followed by a parenthesis should be separated by a space. E.g.

(2) All binary operators (with the exception of ‘.’) should be separated from their operands by spaces. e.g.

payment = interest + principal – deductions;

(3) Expressions in a for statement should be separated by blank spaces. E.g.

Persistence

Java Persistence API (JPA)

The Java Persistence API specification is part of JRS 220:EJB 3.0 and provides “Plain Old Java Object” (POJO) standard and object relational mapping for data persistence.  JPA incorporates many of the concepts and standards of persistence frameworks like Toplink and Hibernate but is an independent API that integrates with J2EE and J2SE applications.

REFERENCES

Writing Robust Java code by Steve Ambler http://74.125.47.132/search?q=cache:bessWUriNMkJ:www.ambysoft.com/downloads/javaCodingStandards.pdf+writing+robust+java+code&cd=1&hl=en&ct=clnk&gl=us

Code Conventions for the JavaTM Programming Language http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
Copyright 1995-1999 Sun Microsystems, Inc. All rights reserved. Used by permission.

Nagler : Coding Style and Good Computing Practices http://www.nyu.edu/classes/nagler/quant2/coding_style.html

Private Fields from collected Java Practices http://www.javapractices.com/topic/TopicAction.do?Id=22

Java Quick Reference guide (http://www.janeg.ca/java2.html )

Dept of IT, Connecticut Government – Java code Conventions http://www.ct.gov/doit/lib/doit/downloads/Addendum_A.pdf