Skip to content
This repository has been archived by the owner on Feb 1, 2020. It is now read-only.

Style Guidelines

Jump to bottom
dwightguth edited this page Aug 28, 2014 · 6 revisions

Syntax

  1. No line should be longer than 99 characters, except import statements, which should be one per line.
  2. Java code must declare the package it is part of.
  3. Imports should not be present unless they are used in the file.
  4. import foo.* should be used sparingly, only when it improves code readability.
  5. Imports should be used whenever a qualified path is required, except in the case of namespace conflicts.
  6. long literals shall be declared with an uppercase "L".
  7. There shall be one outer type per file, named the same as the filename.
  8. Text files shall end in a new line character.

Some suggestions for automatically handling the whitespace issues are gathered at Whitespace Tips.

Code Structure

  1. Code should not follow the pattern if (something) { return true; } else { return false; } or other similar patterns.
  2. Comparison of a String literal to a String object reference should follow the pattern "foo".equals(bar);

Documentation

  1. In interfaces, all methods and the declaration itself should be javadoc'd.
  2. In enums, all enum values and the declaration itself should be javadoc'd.
  3. In classes, fields which have complex meaning, or methods which perform complex tasks, should be javadoc'd, as should the class itself.

Copyright

Copyright notices shall be present in all files, and kept up to date. For example, in Java classes, the first line of any file which was created in 2012 and last modified in 2014 should be:

// Copyright (c) 2012-2014 K Team. All Rights Reserved.

The copyright notice is whitespace and capitalization sensitive. Whenever modifying a file, the copyright notice should be updated to end with the current year. This will be accomplished by means of periodic changes to the checkstyle xml file every January 1.

For information on the precise syntax of copyright notices in other languages, please refer to the checkstyle specification

Whitespace rules

  1. No tabs. All indents should be four spaces.
  2. No trailing whitespace at the end of the line.
  3. no Windows or Mac OS 9 line breaks.

Tips

  • IntelliJ has an option to remove trailing ws on changed lines on save. This is super useful.

  • If you add ?w=1 to Github URL of diff page, it shows diffs ignoring whitespace changes. Just like git diff -w.

  • This vim key mapping makes \W delete trailing whitespace

      noremap <leader>W :%s/\s\+$//<cr>:let @/=''<CR>

  • Adding this to .vimrc will highlight all tabs and trailing whitespace in red. Very handy.

      set hlsearch
  
  highlight ExtraWhitespace ctermbg=red guibg=darkgreen
  match ExtraWhitespace /\s\+$\|\t/

We should only have correctly formatted code now, but here are some tips on merging the big whitespace-fixing commit into an unfixed branch:

  • merge or rebase into your branch with the -Xignore-space-change flag to avoid conflicts
  • The script src/main/scripts/fix_whitespace adjusts whitespace to obey the new guidelines (fixes Windows newlines, but not early Mac ones).
  • Use git diff --ignore-space-change to ensure that you don't see any files that were modified which should not have been.
Clone this wiki locally