Java Glossary : Coding Conventions

Java definitions: 0-9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

You are here : home : Java Glossary : C words : Coding Conventions.

Sun has dared to go were mortals fear to tread and has laid down a set of coding conventions -- how to lay out your code, where to break lines etc. I know of no tool to take messy code and tidy it up, making it conform to the Sun conventions. You can, however, beautify it, which does only a part of the job. Naming conventions are discussed in greater length in the online Java Language Specification. Doug Lea, author of the book Concurrent Programming in Java also has a draft coding standard. Marc W.F. Meurrens maintains a list of coding convention proposals.

Capitalisation

The basic rules are:

packages are all lower case letters. Use your domain name backwards. e.g. package com.mindprod.business;
Class names should start with a capital letter, with embedded words capitalised e.g. EmployeePayRoll.
variables start with a lower case letter with each embedded word capitalised e.g. duckChooserFrame.
static final constants should be all caps with words separated by underscore, e.g. MAXMIUM_IMAGE_HEIGHT
enums properly are classes, so should start with a capital letter. However, it is also considered ok to use all lower case, e.g. enum Fruits { Peach, pear }.
Type names for generics should be a single capital letter, e.g. List <T>.
Don't use punctuation in names, other than _ in static finals.

These rules are particularly important when posting snippets on the Internet. If you violate them, your code will be extremely confusing.

Keyword Order

The Java language specification makes recommendations about the order of modifiers. It strongly encourages the following order:

for fields: public, protected, private, static, final, transient, volatile.
for methods: public, protected, private, abstract, static, final, synchronized, native, strictfp.
for classes: public, protected, private, abstract, static, final, strictfp.

Smalltalk Inspired Conventions

I did contract work for a company called Immuexa. Immuexa follows Sun's coding and naming conventions. In addition Immuexa has the following rules:

The prime zoning law is blend. Your code should look like the code surrounding it. You should not be able to tell who wrote which code. Basically, make it look identical to the boss's code.
No magic literals. Make them into static final constants. There should be no numeric String internationalisation literals. They too should be converted to static final constants.
All Strings should be accessed via the internationalisation methods. There should be no raw string literals.
Variable naming conventions give a hint as to scope, not type:
- local a (e.g. aPoint)
- param p (e.g. pPoint)
- member instance m (e.g. mPoint)
- static s (e.g. sPoint)
- exception X (e.g. XOutOfBounds)
Choose variable names you can read on the phone. Avoid acronyms and abbreviations.
Flag code that needs work with // !! e.g. // !! todo: // !! unclear:
Indent 3 spaces per level, no tabs.
Spaces around ( parentheses ), but so space between a method name and the (.
Put single line if and else clauses without {} on the same line. This is one place where the Immuexa conventions override rather than augment Sun's.
Braces are not indented with the code body they enclose. (I personally prefer the opposite convention.)
Put a blank line before a comment if it has a code line following, and a blank line after a comment that follows a code line, to make it clear which line the comment applies to, and to break the logic into digestible chunks.

You can have rwars about beautifier settings on how { } should align. It does not matter much as long as you are consistent on a project and always beautify before committing to the code repository. Without coding conventions that can be semi-automated with a beautifier, you will get all kinds of false deltas in the repository. This can make it impossible to track who changed what, when.

CodeCompanion checks your code for conformity to 26 coding convention rules.

The Elements Of Java Style

0-521-77768-2

Al Vermeulen (Editor), Scott W. Ambler, Greg Bumgardner, Eldon Metz, Alan Vermeulen, Trevor Misfeldt, Jim Shur, Patrick Thompson

Covers coding conventions and how to write maintainable code. excerpt.

beautifier ¤ CheckStyle ¤ CodeCompanion ¤ DMOZ ¤ Eclipse Conventions ¤ Horstmann conventions ¤ Jindent ¤ Lint ¤ Literate Programming Conventions ¤ Scott Ambler's conventions (pdf) ¤ Sun conventions ¤ Turbine conventions

home	Canadian Mind Products
	mindprod.com IP:[24.87.56.253]
	Your IP:[80.134.30.163]
	You are visitor number 2048.
	Please send errors, omissions and suggestions
	to improve this page to Roedy Green.
	You can get a fresh copy of this page from:	or possibly from your local J: drive mirror:
	http://mindprod.com/jgloss/codingconventions.html	J:\mindprod\jgloss\codingconventions.html