Java Coding Standards

From Apache OpenOffice Wiki
Revision as of 11:28, 6 June 2008 by Jj (Talk | contribs)

Jump to: navigation, search

Purpose

See the C++ Coding Standards for the general purpose of Standards.


Rules for Java

Code Conventions

Java Code Conventions (Conv)

Follow Sun's Java Code Conventions [1] unless one of the rules below says otherwise.

Declarations: Scoping and Names

Naming Conventions (Names)

Descriptive variable, constant and method names must be used in accord with naming conventions.

Javadoc Headers (Javadoc)

Every class / non-private method needs to have a complete header in accordance with the javadoc style. When overriding a method of a superclass this header can be omitted if the content of the superclass description is still true for the implementation of the subclass. In these cases, if using Java5 or later, the @Override annotation must be used.

Comments (Comments)

Use enough comments in the code to make it understandable.

Access Modifiers (Access)

All attributes / methods must have appropriate access modifiers (private/protected/public).

Private Data (PrivData)

Make all class member data private.

Single Class (SingleClass)

Each file must only contain one class (except inner classes).

Explicit Imports (Import)

Don't import complete packages but name the classes to import explicitly.


Implementation Details

Static vs. Non-Static (Static)

Are there static attributes / methods that should be non-static or vice-versa?

Variable Initialization (Init)

All variables need to be properly initialized.

Constants (Const)

Are there literal constants that should be named constants
seems to be the same as MagNum ?

or are there variables that should be constants?

No Magic Numbers (MagNum)

Do not use unnamed constants in your code. Give them descriptive names.

Return Values (Return)

Every method needs to return the correct value at every function return point.

Keep Internals (Internal)

Be careful not to expose member variables by giving out mutable class references as return values. Example: String (immutable) instead of StringBuffer (mutable).

Parentheses (Paren)

Always use parentheses to avoid ambiguity.

Close I/O Resources (IO)

Opened files or connections need to be closed explicitly.

Assert Assumptions (Assert)

Assert (what is the way to do this in Java?) liberally to document internal assumptions and invariants. Don't use assertions for runtime errors. Ensure that assertions don't perform side effects.


Control Flow

Switch Default (Switch)

Every switch statement must have a default case.

Switch Fall-through (FallThrough)

Every case of a switch statement should be ended by a break statement. If that is not the case and a fall-through is intended, then this must be marked by a comment.

No Switch on Types (NoSoT)

Don't use switch, when the cases represent types. Prefer polymorphism.

If to Switch (IfToSwitch)

Nested if-statements should to be converted to switch-statements.
is that really a rule? possible with non-integer values in Java?

Modularity

Duplicate Code (Dupli)

Avoid and remove duplicate code. Put common code into an extra function. Duplicate code may be okay, if otherwise dependencies among so far unrelated modules would be created.

Use of Class Library Classes (Reuse)

Classes and methods from the Java class libraries should be used instead of creating an own implementation.

Make Functions Short (Short)

Make functions short. A comment line or large control structures are hints to extract functions, making the containing function more concise and readable.


Design

No Cyclic Dependencies (CyclDep)

Avoid cyclic dependencies.

No Premature Generalization (PremGen)

Do not generalize before the second occurrence and no later than the third.

One Responsibility (OneResp)

Give one class one cohesive responsibility.

How to Inherit (Inherit)

Inherit to be reused, not to reuse. Else prefer composition over inheritance.

Liskov Substitution Principle (LSP)

Everything one can do with a base class, or is offered by an interface, has to be doable with all derived/implementing classes.

Instantiate Only Leaves (Leaves)

In an inheritance tree of virtual classes, instantiate only the leaves. Make constructors of base classe protected, so instantiation is impossible.


Security

Validate Input (ValInput)

Validate all input coming from external

No Types Overflows (TypesOver)

Be aware that primitive types have limited range.


Interfaces

Consistency (Consi)

Give the same thing the same name everywhere in the interface. Let parameters with the same semantic always occur in the same order in different functions.

Minimality (Min)

Provide only one way to do anything. Move functions that do not belong to the core functionality of the interface to more appropriate locations. For classes: Put convenience functions as non-member functions in the same namespace beside the class.

Unambiguous Overloads (Over)

Can integer overloads of function parameters be ambiguous in Java? Let all overloads of a function be unambiguous. Be aware of default arguments and integral vs. pointer parameters. Provide either only one version of an integral type or (rarely) overloads for all Java integer-types.


The first draft of these guidelines was based on the Perl Coding Standards and the Java Inspection Checklist.


Personal tools