Corfu Style Guidelines

Corfu Style Guidelines

In order to ensure code readability and consistency, Corfu strictly enforces style compliance on all pull requests submitted to the repository through automatic testing using checkstyle in Travis-CI.

The main features of the Corfu Style are:

• Compliance with the Google Java Style Guide with the exception of the indentation rule below.
• Use 4 spaces per indentation level, and 8 spaces for line wrap.
• Limit line length to 100 characters.
• No wildcard imports, and imports should be listed in alphabetical order.
• Comments should be complete sentences.
• Multiline inline comments using /** syntax are not permitted.
• One letter variables should be used sparingly.
• Prefer lombok annotations when possible.
• Annotations should be placed in the order of their importance so that the main ones are noticed easily. If two annotations are having equal importance, place them in alphabetical order.
• Use lf as the newline character.

Log Message Style

High quality log messages are integral to maintaining the debuggability of Corfu. Corfu uses the Slf4j logging framework, with logback as the logger. Log messages are currently not automatically checked, but you should follow the guidelines below:

• Never print log messages directly through stdout or e.printStackTrace().
• Messages should follow the format MethodName[XX]: Message, where
  • XX may be something descriptive about the method invocation. For example, it could be the stream id of an object, or the address of a read operation. It may also be omitted if unecesssary.
  • Message contains a message which is preferably less than 100 characters when printed.
• Whenever possible, use short versions of UUIDs (see the Utils.toReadableID() utility).
• Default to trace level logging for messages.
  • debug level messages should only be used if the messages would be useful for developers debugging components other than the component that is printing the message, or an administrator debugging the entire system.
  • info level messages should be used to print messages which would be helpful to a user, such as a component being reset.
  • warn level messages are used to inform the user of conditions that may cause the system to fail if they are not resolved, which could include unreachable nodes or a disk running out of space.
  • error level messages are used to inform the user of serious but potentially recoverable errors which may be the result of a failing component.
  • fatal level messages inform the user of a condition in which Corfu cannot safely continue operation and will exit.

Unit Testing Style

Good unit tests allow Corfu developers to define and quickly detect unexpected behavior. Maintaining unit test style makes it easier to understand why a test may be failing and what needs to be done to address the failed test. Corfu uses JUnit for unit testing and AssertJ for assertions. We use Coveralls to ensure that submitted patches continue to have sufficient coverage. Unit tests should:

• Follow the code style requirements for non-test code.
• Not produce any console output, either through stdout, e.printStackTrace() or logging.

Git Commit Style

Clean pull requeusts, git commit messages and history help readers and developers understand updates and patches to the Corfu codebase. Code updates to Corfu are submitted through the GitHub pull request mechanism. When submitting a pull request, please ensure that:

• Git commit messages consist of a maximum of 60 characters that concisely describes the patch.
• Git histories do not contain any merge commits (rebase your branch over master).
• The description in the pull request describes in detail why the pull request is being submitted.

We require that at least one reviewer approve your pull request, and that it passes all automatic tests (Travis-CI, Coveralls), before it is ready for merging. Once you have an approval to merge, please condense the history to remove all intermediate commits by squashing and force pushing to your branch.