====== Code Formatting Standards ======
FIXME This page is a work in progress and currently NOT official! FIXME
===== General Conventions =====
As a general rule, Evergreen contributions should follow these basic conventions.
  * Indents - tabs vs. spaces
    * The general rule for all files needing indentation is 4 space indents, no literal tabs
    * The following file types are **exceptions** to this rule
      - Code written in C
      - Database schema/code files (.sql files)
      - Makefiles
      - Plain text files
  * Tokens should be separated by whitespace (i.e '$this = 1' not '$this=1')
  * Opening braces should be on the same line as the corresponding token and 'else' should be "cuddled" <code>
if ($this) {
    that();
} else {
    something();
}</code>not<code>
if ($this)
{
    that();
}
else
{
    something()
}</code>
  * Control structures should be followed by spaces, function names should not (see 'if' vs 'that' above)

===== Tool Specifics =====
==== Vim ====
The following Vim options or something similar (often set via .vimrc) will help with proper indentation:<code>
set tabstop=4
set softtabstop=4
set shiftwidth=4
set expandtab
set backspace=indent,eol,start
autocmd BufEnter ?akefile*,*txt,*out,*csv,*.c,*.h,*.sql set noet "use real tabs in Makefiles, text files, C code, and SQL files
</code>
In addition, the following VIM options have been recommended by a prominent Evergreen developer but are not actually format related :-) :<code>
set hlsearch
vnoremap < <gv
vnoremap > >gv
set nobk
set whichwrap=b,s,<,>,[,]
set smartcase
filetype on
syntax enable
au BufNewFile,BufRead *.xhtml setf html
au BufNewFile,BufRead *.bsh setf java
au BufNewFile,BufRead *.ftl setf html
set bg=dark
let loaded_matchparen = 1
</code>

==== GNU Emacs ====

Add the following lines to your .emacs file and your code will meet the above standards for Perl.

<code>
; Use cperl-mode by default
(defalias 'perl-mode 'cperl-mode)

; cperl-mode doesn't have an add-style command, so we create our
; style in a defun.
(defun evergreen-perl-style ()
  "Set cperl-mode for Evergreen coding guidelines."
  (setq cperl-indent-level  4
	cperl-brace-offset 0
	cperl-continued-brace-offset 0
	cperl-label-offset -4
	cperl-continued-statement-offset 4
	cperl-close-paren-offset -4
	cperl-indent-parens-as-block t
	cperl-tab-always-indent t
	cperl-merge-trailing-else t
	cperl-left-aligned-indent-comments t
	indent-tabs-mode nil))
  
; cperl-mode hook
(add-hook 'cperl-mode-hook
	  (lambda ()
	    (evergreen-perl-style)))
</code>

The above will use these style guidelines on all of your Perl sources. More advanced users might want to configure other styles for different projects and check buffer-file-name to switch styles on a per-buffer basis. You might also want to look into setting many of the cperl-electric-* variables or cperl-hairy. They add a lot of neat features for automatic code completion in Perl.

==== perltidy ====
The following options are recommended when using perltidy to format your Perl code:
  * -b : Backup and modify in place
  * -ce : Enable the "cuddled else" style
Example: <code>perltidy -ce -b Object.pm</code> This will tidy Object.pm and move your original to Object.pm.bak.  Note that this **will** clobber an existing Object.pm.bak file!