Style & Coding Guide
====================

If not explicitly stated here otherwise, the standard Java Coding Conventions apply:
http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html

Further guidelines that are very worth reading:
- Bloch: Effective Java, 2nd Edition: http://www.amazon.com/Effective-Java-Edition-Joshua-Bloch/dp/0321356683/
- Guava User Guide: https://code.google.com/p/guava-libraries/wiki/GuavaExplained
- Google's Java style guide: http://google-styleguide.googlecode.com/svn/trunk/javaguide.html

Some additional information can be found in other files
in this directory, e.g. Logging.txt and Test.txt.

We suggest to use Eclipse for development,
as several parts of this guide are incorporated into the Eclipse project configuration
(indentation, spaces instead of tabs, no trailing whitespaces).
If you do not use Eclipse, please ensure manually that you follow this guide,
or configure your editor/IDE to behave similarly.
Also Eclipse shows more warnings than javac, and these warnings should be taken care of
(make sure to create .factorypath as explained in doc/Developing.txt).

Also check for warnings from the compiler (e.g., warnings for annotation usage),
and from FindBugs.

We want to keep CPAchecker free of warnings!

Code Formatting:
- Check Google's Java style guide mentioned above!
- No tabs in source code!
- 2 spaces for indentation per level.
- No trailing white spaces.
- Do not use automatic code formatting of Eclipse for the complete code,
  it destroys a lot of meaningful manual formatting.
- A block is always surrounded by braces, e.g., if (...) { ...block... }.
- Before { and after } there is one space.
- The { is not on a new line (K&R style braces).
- All statements are on separate lines, no two statements at the same line,
  even in case like if (...) { return; }
- There is no white space between method/constructor name and parenthesis,
  but there is one space between between keywords and parenthesis. Example:
  func();
  if (...) { ... }
  for (...) { ... }
- There is no white space directly inside parentheses,
  except for aligning lines in multi-line conditions.
- There is one space after "," in parameter lists, and none before.
- The ":" in enhanced for loops has one space before and after it.
- When breaking long statements over multiple lines,
  think about indenting them in the following way:
  Object o = x.foo()
              .bar()
              .m();
  (especially for the builder pattern and FluentIterable).
- Aim for a line length of at maximum 80-100 characters.
- There is at least one blank line between methods and constructors,
  more to group related methods.
- There is no blank line required between fields,
  but there is between fields and other members,
  and between unrelated groups of fields.
- Do not align field declarations,
  this gets mis-aligned soon on refactorings anyway.
  Example:
    int foo = -2;
    long x = 3;
  and NOT:
    int  foo = -2;
    long x   =  3;

Spelling:
- Try to avoid typos.
- Names are spelled camel-like, whereEachNewWordStartsWithCapital.
- Type names start with a capital.
- Interfaces are not named with a leading 'I'.
  In general, client code should not need to know whether
  it is using an interface or a concrete class,
  thus there should not be a naming difference.
  Furthermore, a good API should always make sure that
  the best way to do something is also the easiest way.
  When both an interface and a similarly-named class exist,
  the interface is the one that should primarily be used,
  and thus the interface gets the normal/clean/beautiful name,
  and the class the internal/ugly name.
  It is better to have one place using "FooImpl" and hundreds of places using "Foo"
  instead of one place using "Foo" and hundreds of places using "IFoo".
- Method names start lower case and begin with a verb.
- Variable names start lower case.
  Parameters should start with 'p' to avoid confusion with
  local variables or fields.
- For a set of names of concepts (e.g., of files, classes),
  the prefix order induced by the names should
  represent the semantic relation and structure of the concepts.

Compilation:
- Never check in with compile errors.
- Avoid warnings:
  - If there is a way to fix the code, fix it (before committing).
  - Otherwise use @SuppressWarnings.
- Use Eclipse to check for warnings, it shows a lot more than javac.
- After adding/changing an @Option configuration,
  run "ant" to update documentation (before committing).

Design:
- Prefer immutable objects, for own classes and for collections
  (https://code.google.com/p/guava-libraries/wiki/ImmutableCollectionsExplained).
- Avoid null, replace it with real objects, or (at last resort) Optional:
  https://code.google.com/p/guava-libraries/wiki/UsingAndAvoidingNullExplained
- Avoid boolean parameters. They carry no semantics
  and make it hard to understand for the reader what effect they have
  (cf. http://martinfowler.com/bliki/FlagArgument.html)

Configuration options:
- Only use the @Option scheme so your options are automatically type-checked
  and documented.
- Only introduce an option when its meaningful
  (do not add options that nobody would ever want to change).
- Preferably use one of the existing prefixes
  (cpa.YOURCPA., analysis., parser., ...)
  instead of adding a new one.
- Do not use negated predicates as option name
  (use something.enable instead something.disable,
  something.foo instead of something.noFoo etc.).
- Do not forget to update the file doc/ConfigurationOptions.txt
  (done automatically by ant) and commit it together with your changes.

Documentation / Comments:
- The following ranks several places by their importance of having comments:
  * packages (in package-info.java, EVERY package should have one!)
  * interfaces and public classes (at least a short note at the top of their responsibility)
  * public methods in interfaces and classes
  * non-public classes, methods and fields
- Please add comments wherever sensible,
  but make sure to add comments for the top three items!
- All command-line options need to be explained in doc/Configuration.txt.
- All @Option fields need to have a non-empty description
  that explains (to a user) what the option does.

Coding:
- Never have public fields,
  never have non-private non-final fields,
  and try to keep all other non-private fields to a minimum.
- If you use null in method parameters or return values, annotate them with @Nullable.
- Mark fields as final, if they are never modified,
  and try to make them final, if they are modified (-> immutability).
- Prefer enhanced for-loop over List.get(int).
- Use arrays only with primitive types (int, long, etc.)
  or when existing APIs require them.
  Otherwise never use arrays of object types, use lists instead.
  They have a much nicer API, are equally fast,
  and allow you to use ImmutableList and Collections.unmodifiableList()
  to avoid the need for defensive copying while still guaranteeing immutability.
- Never use classes from the sun.* packages, they are not part of the Java API.
  Specifically, use UnsupportedOperationException instead of NotImplementedException.
- Do not use the following classes from the JDK, they all have better replacements:
  Vector (replaced by ArrayList)
  Stack (replaced by Deque interface with implementations ArrayDeque and LinkedList)
  Hashtable (replaced by HashMap)
- The default list implementation is ArrayList (fast and memory-efficient),
  use LinkedList only if you need (i.e., when adding/removing elements in the middle of the list).
  When adding/removing elements at the start of the list, use ArrayDeque.
- When declaring variables of collection types,
  use the interface as type instead of the implementation (e.g., List instead of ArrayList).
  This is especially true for fields, parameters, and return types.
  Do use the Immutable* types from Guava, though, to show that your collection is immutable.
- Use Integer, Double, Long, Boolean etc. only when necessary (this is, inside generics like in List<Integer>).
  In fields, method parameters and return values, and local parameters,
  it is better to use the corresponding primitive types like int.
- Never call the constructor of Integer, Double, Long, Boolean, etc.!
  Use the valueOf() method, it may do caching.
- Never call the String constructor.
  Strings do not need copying, and for other uses there is the valueOf() method.
- Avoid Cloneable and clone(), use copy constructors instead if you need them
  (you don't if you use immutable classes).
- Never swallow an exception.
  If throwing another exception, add the original one as the cause.
  If logging, use the appropriate logger methods (c.f. doc/Logging.txt).
- Always put @Override when implementing an overriding method
  (Eclipse does this automatically).


Automatic code cleanup:
- Most automatic code formatters are not able to follow these rules,
  thus use them carefully. The following is a list of possibilities
  to enforce some of these rules automatically:
- No tabs: Eclipse configuration, SVN commit hook
- No trailing whitespaces: Eclipse configuration applied automatically on save
- Always use braces: Eclipse Code Cleanup
- Opening brace on same line: sed '$!N;s%\(else\|)\) *\n *{%\1 {%;P;D' -i src/**/*.java
- else on same line: sed '$!N;s%} *\n *else %} else %;P;D' -i src/**/*.java; sed '$!N;N;s%\( *\)}\n\n *else %\n\1} else %;P;D' -i src/**/*.java
- Space after keyword: sed -e 's%^\( *}\? *\(assert\|else\|if\|for\|while\|switch\|try\|catch\|finally\)\)\([({]\)%\1 \3%' -i src/**/*.java
- Space before keyword: sed -e 's%^\( *}\)\(else\|catch\|finally\) %\1 \2 %' -i src/**/*.java
- Space between ) and {: sed 's%){$%) {%' -i src/**/*.java
