marc.meurrens@acm.org
(
http://homepages.ulb.ac.be/~meurrens)
http://reality.sgi.com/sandvik/JavaGuidelines.html
Kent Sandvik
(sandvik@sgi.com)
with special thanks to Jordan Hayes for comments about this document.
http://www.ulb.ac.be/esp/ip-Links/Java/joodcs/index.html
[back]
Java Coding Style Guidelines
http://reality.sgi.com/sandvik/JavaGuidelines.html (February 2, 1996. Revision: 1.2)
by Kent Sandvik
(sandvik@sgi.com)
This document contains guidelines for Java coding that I'm personally using. These guidelines are not fixed. The biggest gains you get by conforming to any coding styles are:
In general, these style guides is very much a derivate of the K&R coding style. Most of the Java code I've seen published also conforms to a very similar structure. This is a living document.
Tabs are three spaces.
Block separators conform to the Kernighan&Ritchie style of C programming, or:
if(value != null){
DoSomehing(value);
}
The code is compact, no spaces between keywords, separators, parenthesis. There's a space after each parameter passed in a function or another construct:
void AFunction(int top, int val){
for(int i = 0; i < top; i++){
array[i] = val;
}
}
Everything in Java is scoped to a class, so there's no need to separate local and global variable names from class members.
Classes should have a name that starts with an upper case. If the name is composed of other words, each following word in the name should start with an upper case:
public class MyURLTestApplet extends java.appletApplet{
Final static values (a.k.a enums) are all upper case.
final static int VALUE = 32;
If the constant value has a longer name, you should use underscore to separate the name. This is the only place where you should use underscores (underscores in function names, class names and variable names causes name size bloat).
final static int NORMAL_SIZE = 400;
Variables start with lower case. If the name is composed of other words, each following word should start with an upper case:
String systemName;
The member function names start with lower case. If the name is composed of other words, each following word should start with an upper case.
Parameter names start with lower case. Their names should closely resemble the parameter type value:
String returnName(AppletContext context, URL url)
Variable names should have names that have either an indirect or direct meaning.
int i implies that i is a counter, used for a for case, an array, or something similar. Similarly,
j,k,l should be used for array handling or in cases where we have multiple
count variables.
A temporary generic Exception should be named e.
Graphical variables should have names that closely resembles the intent of the variable:
Point p; Dimension d; Graphics g; Rect r; Image img;
If a temporary value is indicated, the variable should have the word temp or tmp as part of the name.
Random value should have the name rand as part of the name.
If possible, the name should closely specify the intent of the variable or member function:
byte byteArray[]; FileInputStream urlFile; DataInputStream urlData;
If a member field is used globally across the the class, it is declared and initialized at the top of the class:
public class MyClass{
URL mainURL = null;
// ...
If the member field can't be initialized at the top with a known value,
then it should be initialized inside the init() member function, or a similar place.
If the variable is used in a temporary context, declare the variable just before used. The exception might be try/catch cases where an uninitialized variable might trigger a compiler warning:
Point p = comp.location();
All variables should be initialized with a known value. If this value is
not critical, it should be null or 0. This will help concerning finding possible initializer value bugs, and
the compilers will not warn about uninitialized data.
If there's a clear understanding that the class will be used externally, the class is scoped as public. Otherwise it is important to restrict the access to the class.
The following is a personal concept; most likely some will not like this guideline:
Most member fields should be public. There is no need to write accessor and mutator functions, you might as well directly access the field. There are exceptions, though.
Some critical fields that might have issues related to thread/semaphor handling. But in most cases the synchronized keyword should handle this case. Also, if changing the field outside a known API might cause problems, then this member field should be protected or private.
class MyClass{
public int field = 0;
//...
}
MyClass aClass = new MyClass();
aClass.field = 42;
Also, subclasses might want to intercept setting of members. For example:
class MyClass{
int field;
public void setField(int field) {this.field = field};}
}
class MyOtherClass extends MyClass{
public void setField(int f){
if(f > 10 && f < 20)
super.setField(f);
}
}
If we only need to import a specific class, we might as well import this class using the full class name scope:
public class JustOneApplet extends java.applet.Applet{
If we intend to use a larger set of classes in the name space, it is easier to import the name scope:
import java.awt.*;
If a class used for the main class or applet is only used for the specific case, it is OK to add this class at the end of the main class/applet file. However, if it's clear that this class could be reused in other cases, then this class should be placed in a separate source file.
/** */ comment fields to generate html specific code documents, but this is not
necessary in all cases.
This is a collection of generic coding rules and guidelines.
If possible, the return value should contain the whole statement that calculates the return value:
return new Dimension(insets.left + insets.right + w,
insets.top + insets.bottom + h);
The ?:operator is very handy when writing simple, one-line code constructs with
a simple if-then assignment or operation.
pause = (at != null) ? Integer.valueOf(at).intValue() : 3900;
Long member functions are hard to understand. But there has to be a modular approach when breaking a member function into smaller functions.
Send suggestions, comments, bug reports and such to: Kent Sandvik,
sandvik@sgi.com.
Special thanks to Jordan Hayes for comments about this document.
|
Brussels July 8, 1997
mirror updated $Date: 1996/02/02 18:03:48 $, $Revision: 1.2 $. by Kent Sandvik ( sandvik@sgi.com)
published by marc.meurrens@acm.org
(http://homepages.ulb.ac.be/~meurrens)
original URL: http://reality.sgi.com/sandvik/JavaGuidelines.html
current URL: http://www.ulb.ac.be/esp/ip-Links/Java/joodcs/KentSandvik.html
internet programming Links: http://www.ulb.ac.be/esp/ip-Links (ip-Links)
Université Libre de Bruxelles:  http://www.ulb.ac.be (ULB)
La Cambre - Architecture: http://www.lacambre-archi.be
Belgian JAVA User Group: http://www.bejug.org (BeJUG)
| |||||||||||||||||
|
Use this form to send your feedback and/or submit a link
| |||||||||||||||||
Conventions used in these pages:
html file,  text file or  java or CPP source located on our site
 download area (on our site) or  file to be downloaded (use the right button of your mouse)
document on a belgian academic or scientific site
document (on another site) or  link to be fixed or  link we didn't visit/evaluate; documents indicated with their full URL will be displayed in their own "top" window.
 ftp download or
 file to be downloaded (use the right button of your mouse)
indicates a "mailto" link.
Click on the separator to reach a higher level in the page or site hierarchy.
| |||||||||||||||||
| |||||||||||||||||
