My Coding Styleguide
The following list gives a short overview of special programming techniques that are used inside all of my projects.
- Classes always start with an upper case identifier and use camel case for naming (e.g.
- Abstract classes always start with the term
- All interfaces are named starting with a capital 'I' followed by a second uppercase character (like in
IHasID). By default all interfaces contain only read-only methods except the interface name starts with
IMutablein which case the interface also contains modifying methods.
- All enumerations are named starting with a capital 'E' followed by a second uppercase character (like in
- All member variables are private or protected and use the Hungarian notation (like
aList). The used prefixes are:
afor all kind of objects that do not fall into any other category (e.g.
aList) - this also includes all kind of arrays, even of primitive type
bfor boolean variables (e.g.
cfor character variables (e.g.
dfor double variables (e.g.
efor enum variables (e.g.
ffor float variables (e.g.
nfor byte, int, long and short variables (e.g.
sfor String variables (e.g.
- The scope of a field is indicated by either the prefix
m_for instance (member) fields, and
s_for static fields. A special case are "static final" fields which may omit this prefix and use only upper case character (e.g.
public static final boolean DEFAULT_VALUE = true;)
- Private methods (no matter if static or not) always start with a single underscore (
_) and are not declared
finalas they are implicitly final.
- All methods returning collections (lists, sets, maps etc.) and arrays are usually returning copies of the content. This helps ensuring thread-safety (where applicable) but also means that modifying returned collections has no impact on the content of the "owning" object. In more or less all cases, there are "add", "remove" and "clear" methods available to modify the content of an object directly. All the methods returning copies of collections and arrays should be annotated with
@ReturnsMutableCopy. In contrast if the inner collection or array is returned directly (for whatever reason) it should be annotated with
@ReturnsMutableObjectin which case a special description is provided in the annotation. If an unmodifiable collection is returned, the corresponding annotation is
Collections.unmodifiableListetc.) (this is not applicable for arrays).
- For all non primitive parameter the annotations
@Nullableare used, indicating whether a parameter can be
nullor not. Additionally for Strings, collections and arrays the annotation
@Nonemptymay be present, indicating that empty values are also not allowed. All these annotations have no impact on the runtime of an application. They are just meant as hints for the developers.
- Domain model classes are annotated with the FindBugs annotations
@NotThreadSafeto indicate their thread-safety level.
- All projects include Eclipse project files (
- All projects use Apache Maven 3.x for building (
- Most projects contain a FindBugs configuration. Therefore the file
findbugs-exclude.xmlmust be present in each projects root directory.
- All logging is done via SLF4J. The logger is more or less always declared as
private static final Logger s_aLogger. In certain cases it might also be
- All projects (except for JDK extensions) use ph-commons which is the most basic library and can be considered a JDK extension.
- Synchronization (thread-safety) of code is achieved using
java.util.concurrent.locks.ReadWriteLockwhich allows multiple readers but only a single writer to access a critical section at a time. For projects using JDK 8 (or higher) the respective class
com.helger.commons.concurrent.SimpleReadWriteLockis used for better Lambda support.
- Interface methods never contain the visibility specifier as it is implied (public).
- Don't use interfaces which contains only constant values as this bloats the overall namespace of all classes implementing it. Use static imports if absolutely necessary.
- No class defines a
serialVersionUIDas this is automatically done by the Java runtime upon execution.
JDK 8 specialties
- Starting with ph-commons 8 synchronization is done using
com.helger.commons.concurrent.SimpleReadWriteLockwhich is a special
ReeentrantReadWriteLockimplementation with better support for the usage with Lambdas.
- I'm not using the stream API since there are performance considerations and the regular iteration usually works pretty efficient and helper methods with Lambdas are available. Instead the class
CollectionHelperoffers some simple abstractions, for the rest I loop myself. I'm a big fan of "better the developer has increased effort than the user is impacted negatively".
- Starting with ph-commons 8 a set of collection interfaces and classes starting with
CommonsArrayList) are used because they offer tons of default sanity methods.
- Usually the extended collections are used as return types (where use is expected) but not as parameter types (which should be as narrow as possible)