DeveloperGuide
This project aims to produce high quality software. Therefore it is very important that the code is well designed, documented and tested. No sub-project should be released (as official version) if it has NOT been tested intensively (though it can obviously still have bugs).
The project is using maven as build- and management-tool. Therefore the maven conventions apply to this project. If you are NOT familiar with maven please read the following guides:
For version control we are using GIT. Download and install git. If you are using windows you might also want to install tortoisegit.
We are using devonfw-ide.
When asked for the settings URL after running setup please enter: https://github.com/m-m-m/settings.git
The code produced by this project follows a common code-style. To check these rules, configurations for checkstyle and eclipse are provided (see Setup). Further there are additional rules to follow:
-
Names for classes and interfaces are english words that describe the type briefly. They are in the typical caml case (e.g. AbstractWidget). Shortcuts and acronyms are NOT capitalized as part of names (e.g.
XmlUtiland notXMLUtil). -
There are no artificial conventions for names of interfaces (like
Ias prefix orIFas suffix). The interfaces should have the nice names while implementations may be named artificial (*Impl). -
The code should be well documented using JavaDoc. It does NOT help just to satisfy checkstyle with some generated JavaDoc nonsense. Please help to maintain the JavaDoc of the code and make it precise. Make intensive use of the
{@link FooClass}constructs to specify what you are talking about.
This project follows the principle of a component-oriented-design. So what is a component? First of all a common definition:
"A component is a reusable piece of software that offers its functionallity through a well-defined and self-contained API. Its implementation is therefore exchangeable and can be composed using other components."
While such definition is easily agreed by most developers it is still very unprecise. If you want to drag the term component down to the code, one might mean some specific interface another one thinks about the content of a java-package. The following section defines rules that help to track this down to the code and give it a common structure. However the most important part about the design is how functionallity is grouped and exposed in the API, what can never be expressed or checked by formal rules.
The projects package namespace is io.github.mmm. All module names and packages should be sub-packages of this namespace.
Java makes resource handling very easy. The trade-off is that there are many common mistakes developers do because they stop thinking about resource management.
If you deal with streams (InputStream, OutputStream, or related stuff) please be very careful to ensure they are closed properly. Whenever an API method takes a stream as parameter, the JavaDoc must specify whether the stream is closed or not. If you want to close a stream make proper use of finally statements. The following example does NOT always close streams properly:
FileInputStream sourceStream = new FileInputStream(source);
FileOutputStream destinationStream = new FileOutputStream(destination);
FileChannel sourceChannel = sourceStream.getChannel();
try {
sourceChannel.transferTo(0, sourceChannel.size(), destinationStream.getChannel());
} finally {
destinationStream.close();
sourceStream.close();
}A correct version looks as following:
FileInputStream sourceStream = new FileInputStream(source);
try {
FileOutputStream destinationStream = new FileOutputStream(destination);
try {
FileChannel sourceChannel = sourceStream.getChannel();
sourceChannel.transferTo(0, sourceChannel.size(), destinationStream.getChannel());
} finally {
destinationStream.close();
}
} finally {
sourceStream.close();
}However, this is still problematic as an exception during transfer may be lost if close() will also cause an exception.
This is a design flaw of Java that has been somewhat corrected in java7. Until then we already support this with NlsThrowable.
The above also applies to transactions of sessions that have to be closed. The difference is that you will get into trouble way faster if your code is wrong.
The garbage-collector is a fine thing, but anyway it does NOT prevent you from creating memory-holes in your software. Therefore you should carefully dereference objects that are no longer needed. This especially applies to objects stored in collections. If you use a map to cache objects you need to ensure that the cache size can only grow to a defined maximum and objects can still be dereferenced using weak- or soft-references.
In non-functional programming languages it is complicated to deal with concurrent access as you have shared resources. Please avoid static without final. If you design a class always consider if it is possible to do something in a thread-safe way. On the other hand never assume that some implementation is thread-safe if NOT explicitly specified in the JavaDoc.
For each sub-project module-tests should verify the integrity of the code. Therefore JUnit and AssertJ are used. Maven (surefire) is used to verify the unit-tests during the build process. The test-results and test-coverage are generated as report via maven-site or sonar-qube build. It is hard to reach a high coverage but this is a goal of the project to increase the coverage continuously.
This documentation is licensed under the Creative Commons License (Attribution 4.0 International).
