Skip to content
This repository was archived by the owner on Jun 13, 2025. It is now read-only.

Code Guidelines

Jump to bottom
Floria Lamprecht edited this page Sep 20, 2016 · 2 revisions

Code have to be readable

Like the caption says, the most important rule is to make the code readable!

Encoding

All java files should be encoded as UTF-8. Non-ASCII characters should be entered as "\uXXXX" with XXXX representing the codepoint.

Use one statement per line.

This makes it easier to pick out the statements and improves readability a lot.

Line and class length

the readability of classes and lines goes down with increasing length. Try to keep classes shorter than 1000 lines and lines under 120 characters

Braces

We do not say that braces have to be in a new line or after the declaration of the class or method.

But we want that every if statement has braces. Our code does not match this expectation, but we will improve this while working on it.

Naming

Basic Conventions:

  • DO NOT use single character names! Except: Focused use in small loops.

  • Use nouns for class, package, and variable names.

  • Use verbs for method names.

Detailed Recommendations:

Type

Examples

Remarks

File

BasicCalculation

Camel case, first letter capitalized, nouns

Named in accordance to the contained class/interface + .java suffix.

Package

Lower case, no dashes or underscores

Classes, Interfaces,
Abstract Classes

BaseCalculation, HttpRequest, SerializableListImpl

Camel case, first letter capitalized, nouns

Exceptions

DivisionByZeroException, SAXException

Like classes, suffix: Exception

Methods

doSomething, calculateAverage

Camel case, first letter lower case, verbs

Test Methods

testCalculateAverage()

Like methods, prefix: test

Constants

ROOT_PATH, COUNT_OBJECTS

All upper case, words separated by underscore

Variables

count, firstName

Camel case, first letter lower case

Member Variables

sampleVariable, width

Like variables

Method Parameters

name, availableResources

Like variables

Comments

Every module class should start with its specific header.

Usage Guidelines:

  • A reference to the license / copyright statement MUST be included. Normally, It should just refer to a “LICENSE” file which is part of your project. This practice helps to avoid unnecessary maintenance work and is often sufficient from the legal point of view.

  • The header should NOT mention the authors.

[[CodeGuidelines-Commentthe“right”things.]] Comment the “right” things. ^^^^^^^^^

  • Which things need to be documented?

    • Every public class needs a Javadoc comment.

    • Every public method which is non-trivial needs a Javadoc comment.

    • But most important: Do NOT comment the obvious! If there is no information to add, you should just leave out the comment!

  • What should I document?

    • Describe the “big picture”.

    • Describe the edge cases and surprises which the invoker might face.

    • Anticipate likely questions.

    • Keep your comments compact.

  • How should I format the Javadoc comment?

    • Describe parameters, return value and exceptions using the Javadoc syntax.

  • Find a good mixture of good class/variable/method names, Javadoc, and unit tests.

Clone this wiki locally