Java Coding Standards
Purpose
This document is intended to increase readability and consistency of Java code written for our projects. For more information, please refer to the Sun Code Conventions for the JavaTM.
Naming Conventions
1. Package
A package is a set of source files that implement a cohesive set of related functionality.
· Package name will follow the pattern, com.telephia.packagename. such as com.telephia.bulldog, com.telephia.skylos.admin.
· Package members will be in a namespace, the name of which is the package prefix, such as class DataManager, class DataObjects.
2. Classes, methods, variables
Here are a few guidelines for naming classes, methods and variables:
· Prefer nouns for class names and verbs for methods.
· Variable names should be short yet meaningful. The choice of a variable name should be mnemonic. One-character variable names should be avoided except for temporary "throwaway" variables.
· Choose names that are consistent and unambiguous with other parts of the project.
· Borrow names from the related Design Pattern, if applicable. (For example, Singleton, NullObject, Factory). E.g. HtmlTamplteFactory.
· Avoid names that are vague or too general (examples - class CObject, CBlah.ProcessEvent()). If a vague name is appropriate for your class, you have a vague class.
· If abbreviations are used, make them consistent. Prepare a list of standard abbreviations (e.g. DSF==DataStreamFilter, RL==ReportLibrary).
3. Low/Upper-case Rules
|
Identifier Type |
Rules for Naming |
Examples |
|
Package name |
The prefix of a unique package name is always written in all-lowercase ASCII letters and should be one of the top-level domain names, currently com, edu, gov, mil, net, org etc. |
com.telephia.bulldog com.telephia.skylos.admin |
|
class name |
Class names should be nouns, in mixed case with the first letter of each internal word capitalized. |
class Raster; |
|
interface name |
Interface names should be capitalized like class names. |
interface RasterDelegate; |
|
instance method (non-static) |
Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized. |
run(); |
|
class method (static) |
Same as instance method |
blahFunc() (Invoke with classname.blahFunc(), never instancename.blahFunc()). |
|
local variable |
All variables are in mixed case with a lowercase first letter. Internal words start with capital letters. |
int i; char c; float myWidth; |
|
instance variable (non-static) |
Same as local variable |
blahVar (this.blahVar is required to distinguish arguments from instance variables). |
|
class variable (static) |
Same as local variable |
blahVar (use classname.blahVar to mention that this is a class variable). |
|
constant |
The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (Usually defined in an interface) |
static final int MAX_WIDTH = 999; |
Comments
Here are the three types of comment, with the circumstances in which they should be used:
|
Type of comment |
Purpose |
|
Javadoc comment /** |
All javadoc comments, as required. This includes all external documentation (that is, intended for the users of a class). For more info, please refer to http://java.sun.com/javadoc/writingdoccomments |
|
Block comment /* disable printing debug info * System.println((UserID); |
Block comments are used to provide descriptions of files, methods, data structures and algorithms. Block comments may be used at the beginning of each file and before each method. They can also be used in other places, such as within methods. Block comments inside a function or method should be indented to the same level as the code they describe. |
|
Endline comment // for pie chart |
commenting out single lines of code. Reasonable endline comments. (Very short comments, after a line of code). All internal documentation (that is, intended for the maintainers of a class). |
Whitespace conventions
· Tab spacing = 4.
· Indent using tabs.
Brace style
No specific rules for this. The following style is preferred:
void blah()
{
try {
if (true) {
// do something
}
}
catch (Exception) {
// do something
}
}
Indenting style
This style for defining and calling methods with long argument lists is preferred:
void blah(int a,
boolean b,
Blah c)
{
// do something
}
Class template
|
/* * Telephia Inc. * project name: Bulldog * file name: Boo.java * Copyright (c) 2001 by Telephia, Inc. All Rights Reserved. */ package com.telephia.bulldog; import com.telephia.skylos.common.*; /** * Class description goes here * @author guy * @version x * createdOn 03/20/01 * lastModified 07/20/00 guy */ public class Boo { // Declare Variables // Constructors // Instance Methods // Class Methods (including static initializers) } |
Method template
|
/* * method description goes here * @param name type * @return name type */ public String getFolderStatus( Long folderID ) { return (String)folderStatus.get(folderID); } |