Coding and Documentation Style

Owned by Andre van Hoorn
Last updated: Jul 04, 2018 by Robin FinkbeinerVersion comment
2 min read

Coding Style and Formatting

In Kieker we use a common set of rules how program code is formatted and how it should be documented. Tooling such as Checkstyle, PMD and Findbugs are used to enforce specific programming styles and those formatting regulations. Furthermore, we defined a setup for Eclipse to support formatting rules and coding styles. In general we use the  Eclipse Coding Conventions (ECC) which are by themselves a derivate of the  Java Coding Conventions (JCC) for Java.

We define two deviations from the ECC which are:

  1. We allow 165 characters per line instead of only 80 characters. As modern screens are way bigger than those decades ago, the limitation to 80 characters in conjunction with human-readable method names result in ugly line-wrappings. To reduce this problem we double the line length.
  2. All parameters of methods are declared final as long they are not modified internally in the method.

Tutorial: Kieker Coding Conventions in Eclipse

How to set up Eclipse for Kieker Coding StyleJavadoc

  • Use the @since tag for new classes, interfaces, enums and annotations. Use the tag also for all methods within interfaces.
  • Use the @author tag if you create a new class, enum, interface or annotation.
  • Setter and getter methods don't have to be commented.
  • Do not use package javadocs.
  • If you create a new class, interface, enum or annotation: Add a meaningful comments which describes what the component does and why it exists.
  • Do not mix javadoc and TODO comments. TODO comments should always be located outside of javadoc blocks.
  • In general document why something exists not what it does, as this should be obviously follow from the code. In addition you may add documentation to the developer guide.

Comments

  • Use // for "normal" (non-javadoc) comments
  • If you use //NOCS or //NOPMD add the reason in brackets behind the comment.