In general, we follow Code Conventions for the Java Programming Language, however there are some specifics, which can be useful to know for db4o users and core contributors.
This document is supposed to emphasize some of the java coding style recommendations used by db4o and explain db4o specific coding style requirements.
All code files must have copyright.The normal db4o copyright notice should be created as the standard template in your Eclipse workspace for db4o development.
Window + Preferences + Java + Code Style + Code Templates + Code + New Java Files
/* Copyright (C) 2004 - 2007 db4objects Inc. http://www.db4o.com */
${package_declaration}
${typecomment}
${type_declaration}
All names should be written in English.
English is the preferred language for international development.
Package names should be in all lower case.
com.db4o.reflection
Class names should be nouns and written in mixed case starting with upper case.
ObjectContainer, Configuration
Method names must be verbs and written in mixed case starting with lower case.
isReadOnly(), rename()
Abbreviations and acronyms should not be uppercase when used as name.
IoAdapter(); // NOT: IOAdapter
Using all uppercase for the base name will give conflicts with the naming conventions given above and will reduce the readability.
Type names must be nouns and written in mixed case starting with upper case.
Db4oList, TransientClass
Variable names must be in mixed case starting with lower case. Variables should have full sensible name, reflecting their purpose.
listener, objectContainer
Private class variables should have underscore prefix.
public abstract class IoAdapter {
private int _blockSize;
.....
}
Underscore prefix will help a programmer to distinguish private class variables from local scratch variables.
Scratch variables used for iterations or indices should be kept short. Common practice is to use i, j, k, m, n for numbers and c, d for characters.
Constants names (final variables) must be all uppercase using underscore to separate words.
ACTIVATION_DEPTH, READ_ONLY
It is a good practice to add methods to retrieve constant values for user interface:
boolean isReadOnly() {
return _config.getAsBoolean(READ_ONLY);
}
Normally we do not use get/set prefix for methods accessing attributes directly, unless such usage adds valuable information:
public void setStateDirty() {}
In other cases feel free to access attributes by names:
clientServer(), configuration()
is(can, has, should) prefix should be used for boolean variables and methods.
isDirty(), canHold(reflectClass)
Using the is(can, has, should) prevents choosing bad names like status or flag. isStatus or isFlag simply doesn't fit, and the programmer is forced to choose more meaningful names.
Setter methods for boolean variables must have set prefix as in:
public void setStateDirty() {}
The term initialize can be used where an object or a concept is established. classIndex.initialize(_targetDb);
Abbreviations like init must be avoided.
Complementary names must be used for complementary entities:
get/set, add/remove, create/destroy, start/stop, insert/delete, increment/decrement, old/new, begin/end, first/last, up/down, min/max, next/previous, old/new, open/close, show/hide, suspend/resume, etc. For example:
startServer();
stopServer();
This convention helps to distinguish the borders of a logical operation and to recognize opposite action methods.
Abbreviations in names should be avoided.
copyIdentity (); // NOT: cpIdentity, NOT:copyId
However some well established and commonly used acronyms or abbreviations must be preferred to full names:
html // NOT: HypertextMarkupLanguage
cpu // NOT: CentralProcessingUnit
Named constants should be used instead of:
- magic numbers:
if (blockSize > MAX_BLOCK_SIZE) // NOT: blockSize > 256
- fixed phrases:
if (fieldname == CREATIONTIME_FIELD) // NOT if (fieldname == "i_uuid")
This convention gives a programmer an idea about the meaning of the constant value. At the same time, it makes it easier to change the constant value: the change must be made only in one place.
Internal class implementations should be placed in com.db4o.internal package. This helps to keep the top-level API smaller and more understandable.
com.db4o.query.Evaluation
has implementation in
com.db4o.internal.query.PredicateEvaluation
Class and Interface declarations should be organized in the following manner:
class
or interface
statement. static
) variables in the order public
, protected
, package
(no access modifier), private
.public
, protected
, package
(no access modifier), private
.Group class methods by functionality rather than by scope or accessibility. For example, a private class method can be in between two public instance methods. The goal is to make reading and understanding of the code easier.
Use Lock4#snooze(), #awake() instead of Object#wait directly for CF reason.
Use blank lines to separate methods, class variable declarations of different scope, and logical units within a block of code. Consider extracting logical blocks of code into separate methods
Import declarations should only include package name:.
import java.util.*; // NOT: import java.util.List;
Modern IDEs, such as Eclipse, provide an automated way to create correct import statements (see "Source/Organize Imports" command in Eclipse).
Local variables should appear at the beginning of a code block. (A block is any code surrounded by curly braces "{" and "}".) Try to initialize the variable immediately to prevent using uninitialized values.
The exception to the rule is indexes of
loops, which in Java can be declared in the for
statement: for
for (int i = 0; i < maxLoops; i++) { ... }
Avoid local declarations that hide declarations at higher levels. For example, do not declare the same variable name in an inner block:
int count;
...
myMethod() {
if (condition) {
int count = 0; // AVOID!
...
}
...
}
Never use exception#printStackTrace() in db4o productive code.
There are three possible choices that can be used:
Supply your code with javadoc comments. All public classes and public and protected functions within public classes should be documented. This makes it easy to keep up-to-date online code documentation. If a class or a method is not part of public API use @exlude
tag. For further details, see "How to Write Doc Comments for Javadoc"
All comments should be written in English. In an international environment, English is the preferred language.
Avoid using comments to explain tricky code, rather rewrite it to make it self-explanatory.
For more information see: Code Conventions for the Java Programming Language.
This document was compiled based on db4o team coding practices and the following documents:
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
http://geosoft.no/development/javastyle.html
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html