The GenABEL project coding style guidelines

1. General
- 1.1. White space
- 1.2. Other
2. R
- 2.1. Code
- 2.2. Documentation
3. C/C++
4. LaTeX
5. Configuring editors and IDEs to support the guidelines
- 5.1. Eclipse
- 5.2. Emacs
  - 5.2.1. Emacs 23
  - 5.2.2. Emacs 24

This document describes the coding style guidelines of the GenABEL project. At present it is considered work in progress. As the name says these are guidelines, not rules. We don't want these guidelines to restrict people from contributing code to the project. On the other hand, respecting these guidelines will lead to uniform and more easily maintainable code and consequently we encourage everyone to follow them.

1 General

1.1 White space

commas should be followed by a space
operators (= + - * && >= etc.) should be surrounded by a space (and in R the <- operator too)
a file should always have a newline at the end (Why?)
don't use tabs (as everyone seems to have a different setting for the tab stop): use spaces. How many spaces is up for debate (YA & LCK suggest 4). Of course Makefiles are exempt from this rule as tabs are mandatory
no (unnecessary) empty lines. Empty lines separating (logical) blocks of code are OK, empty lines at the bottom of a file, a function, an if-statement are not.

1.2 Other

lines should not be longer than 80 characters
do not use one-character variable names, except for simple counters in loops
issues to be be fixed should be represented as:
```
//FIXME(name_of_person): explanation what is wrong.
```
This makes looking and finxing for this types of problems easier
things to do must be annotated with:
```
//TODO(name_of_person): explain what to do
```
Don't be shy and put your name in there if this is something that you expect will take a while.
code that is old/broken should be removed (we have our version control system so we can always go back to see how things were in the past)
functions should not contain more than ~30 lines. If you need more: you probably need a new function anyway to separate logical parts of the code.
seperate code that outputs to file or console from rest of the code

2 R

2.1 Code

Use the <- operator for assignments, not =
use codetools in R to check your functions

2.2 Documentation

We prefer that all documentation should be in roxygen2 format.

3 C/C++

style of brackets: is the opening bracket on the same line as the name of the loop/function or on a new line on its own? (e.g. K&R, Allman or bsd style) TODO: decide which one
both brackets of else statements should be on the same line Depends on previous item
always use {} in if clauses/for loops (even if there is only one statement in the clause/loop
make sure your code compiles without warnings/errors using
```
gcc -wall
```

4 LaTeX

5 Configuring editors and IDEs to support the guidelines

5.1 Eclipse

This works for Eclipse IDE for C/C++ Developers Juno Service release 2. To replace tabs with spaces go to

Preferences -> C/C++ -> Code Style -> Formatter
Preferences -> StatET -> R code Formatting

5.2 Emacs

Add the following to your ~/.emacs file (tested in Emacs 23 and 24).

5.2.1 Emacs 23

;;; Trailing white space stuff
;; Show trailing white space in orange
(setq-default show-trailing-whitespace t)
(set-face-background 'trailing-whitespace "orange1")
;; nuke whitespaces when writing to a file
(add-hook 'before-save-hook 'whitespace-cleanup)
;; Don't insert tabs when indenting regions (setq-default is used here
;; to only overwrite this in buffers that do not have their own local
;; values for this variable)
(setq-default indent-tabs-mode nil)

;; always insert at final newline character (if not present yet) when
;; saving a file.
(setq require-final-newline t)


;;; ESS mode (R, S, etc.)
(add-hook 'ess-mode-hook
   (lambda ()
     (auto-fill-mode t)          ; Turn on auto-fill-mode
     ; Set pdflatex as the default command for Sweave (default: texi2pdf)
     (setq ess-swv-pdflatex-commands (quote ("pdflatex" "texi2pdf" "make")))
     ))


;;; C-mode:
;; change C indentation style ("{" directly under "for" etc.)
(setq c-default-style "bsd"
   c-basic-offset 4)            ; Indentation of 4 spaces
;; Turn on auto fill mode (max 80 columns)
(add-hook 'c-mode-common-hook 'auto-fill-mode)

;;; LaTeX using AucTeX
(load "auctex.el" nil t t)
(add-hook 'LaTeX-mode-hook
(lambda()
   'turn-on-auto-fill     ; Set max of 80 columns
 ))

 ;; Emacs' regular latex mode (when AucTeX isn't present)
 (add-hook 'latex-mode-hook 'turn-on-reftex)
 (add-hook 'latex-mode-hook 'turn-on-auto-fill)

5.2.2 Emacs 24

Emacs 24 has a new mode, called prog-mode, from which all programming modes inherit.

;;; Trailing white space stuff
;; Show trailing white space in orange
(setq-default show-trailing-whitespace t)
(set-face-background 'trailing-whitespace "orange1")
;; nuke whitespaces when writing to a file
(add-hook 'before-save-hook 'whitespace-cleanup)
;; Don't insert tabs when indenting regions (setq-default is used here
;; to only overwrite this in buffers that do not have their own local
;; values for this variable)
(setq-default indent-tabs-mode nil)
;; Apparently Emacs 24 has a bug and tabs can reappear again. This
;; fixes it. Thanks to
;; http://stackoverflow.com/questions/7349487/emacs-different-tab-indent-settings-in-different-modes
;; for the fix.
(defadvice whitespace-cleanup (around whitespace-cleanup-indent-tab
                                      activate)
  "Fix whitespace-cleanup indent-tabs-mode bug"
  (let ((whitespace-indent-tabs-mode indent-tabs-mode)
        (whitespace-tab-width tab-width))
    ad-do-it))

;; always insert at final newline character (if not present yet) when
;; saving a file.
(setq require-final-newline t)


;;; Customisation of prog-mode. All programming modes inherit from
;;; this mode. This mode exists since Emacs 24.
;; Wrap lines after 80 columns
(add-hook 'prog-mode-hook 'auto-fill-mode)


;;; ESS mode (R, S, etc.)
(add-hook 'ess-mode-hook
   (lambda ()
     ; Set pdflatex as the default command for Sweave (default: texi2pdf)
     (setq ess-swv-pdflatex-commands (quote ("pdflatex" "texi2pdf" "make")))
     ))


;;; C-mode:
;; change C indentation style ("{" directly under "for" etc.)
(setq c-default-style "bsd"
   c-basic-offset 4)            ; Indentation of 4 spaces
;; Turn on auto fill mode (max 80 columns)

;;; LaTeX using AucTeX
(load "auctex.el" nil t t)

;; Emacs' regular latex mode (when AucTeX isn't present)
(add-hook 'latex-mode-hook 'turn-on-reftex)
(add-hook 'latex-mode-hook 'turn-on-auto-fill)