Difference between revisions of "Java Coding Standards"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Assert Assumptions (Assert))
(Implementation Details)
Line 43: Line 43:
 
===== Keep Internals (Internal) =====
 
===== Keep Internals (Internal) =====
 
Better not expose member variables by giving out mutable class references as return values. Example: String (immutable) instead of StringBuffer (mutable).
 
Better not expose member variables by giving out mutable class references as return values. Example: String (immutable) instead of StringBuffer (mutable).
 +
 +
===== Use a Single Return Value (ReturnVal) =====
 +
Do not change parameter references in methods as a substitution for return values.
  
 
===== Parentheses (Paren) =====
 
===== Parentheses (Paren) =====

Revision as of 09:28, 13 June 2008

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. Keep local naming conventions.

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). 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?

Static Initializers

Avoid usage of classes other than from the Java class libraries in static initializers.

Variable Initialization (Init)

All variables need to be properly initialized.

Constants (Const)

Are there literal constants that should be named constants or are there variables that should be constants?

Keep Internals (Internal)

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

Use a Single Return Value (ReturnVal)

Do not change parameter references in methods as a substitution for return values.

Parentheses (Paren)

Always use parentheses to avoid ambiguity.

Close I/O Resources (IO)

Opened files or connections need to be closed explicitly. Keep in mind that throwing exceptions can hinder closing resources. In those cases use finally to guarantee closing resources.

Assert Assumptions (Assert)

Assert liberally to document internal assumptions and invariants. Don't use assertions for runtime errors. Ensure that assertions don't perform side effects.

Exception Handling (Exception)

Use exception-handling to handle errors, this helps everyone to identify and locate errors. Try to use the standard exceptions of the Java API and avoid empty Catch-blocks.

Casting (Cast)

Avoid casting values to reduce ClassCastException or may be a data loss. Try to use generics or use safe casts.

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.


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. If a subclass is allowed to omit the implementation of a given method, then this should be listed in the documentation of the base classes' method.


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. All parameters used for output should be at the end of the parameter list. Additionally it needs to be stated in the method documentation if a parameter is an output parameter.

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.


OpenOffice.org

Query Interface (Qifc)

UnoRuntime.queryInterface() is costly regarding performance. When it has to be used in loops, it should be done outside of the loop and the result reused inside.

License (Lic)

tbd



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


Personal tools