Code Formatting Standards

This page is a work in progress and currently NOT official!

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
    1. Code written in C
    2. Database schema/code files (.sql files)
    3. Makefiles
    4. 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"

  if ($this) {
      that();
  } else {
      something();
  }

  not

  if ($this)
  {
      that();
  }
  else
  {
      something()
  }

• Control structures should be followed by spaces, function names should not (see 'if' vs 'that' above)

The following Vim options or something similar (often set via .vimrc) will help with proper indentation:

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

In addition, the following VIM options have been recommended by a prominent Evergreen developer but are not actually format related :

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

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

; 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)))

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.

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:

perltidy -ce -b Object.pm

This will tidy Object.pm and move your original to Object.pm.bak. Note that this will clobber an existing Object.pm.bak file!