Code Guidelines

Readable code

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 convention

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	de.dlr.sc	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
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.

Comment the “right” things

• What needs 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.