“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).
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.
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.
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.
|File type||Suffix used|
JAVA Naming conventions:
|Boolean getter member functions||Prefix fieldname with ‘is’
Prefix fieldname with ‘has’ ‘can’
|isValid() , isAtEnd(), hasCollateral(),|
|Constructors||Use the same name as their class||CheckingsAccount()|
|Exceptions||Begin with letter ‘e’||eDivideByZero|
|Getter member function||Prefix the fieldname with ‘get’||getLimit(), getFirstName()|
|Interfaces||-Use English descriptive words preferably verbs -End with ‘able’, ‘er’.||Prompter,Projectable|
|Loop Counters||*Okay to use single letter variables i, j, k *Organizational standards preferable||i, j, k loopCounter|
|Setter member function/ mutators||Prefix the fieldname with ‘set’ *||setLimit()|
|Final variables or Constants||All uppercase
Use underscore to separate words
|Variable||Must be in mixed case starting with lower case.||wireLength,
|Private classs variables||Name representing a private class variable should have an underscore suffix|
*Adheres to the general naming conventions for methods: Names representing methods must be verbs an and written in mixed case starting with lower case.
(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
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
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
Declare the fields and member functions of a class in the following order:
- Private Class Variables
- Public member functions
- Protected member functions
- Private member functions
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:
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.
(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.
testClass.fchar = fooclass.lchar = ‘a’; // avoid
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.
- 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:
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.
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 is much more than a matter of style. Correct indentation helps in identifying control flow and blocks of code.
|Hanging-paragraph style (Preferable)||No-style (Avoidable)|
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 improve readability by setting off sections of code that are logically related.
Use two blank lines:
- between class and interface definitions and
- between sections of a source file.
Use one blank line between:
- logical sections within a method.
(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.
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.
Writing Robust Java code by Steve Ambler http://126.96.36.199/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