WormBase Coding Standards and Style Guide

Quick Reference

Entity	Format
module	CamelCase
method (public)	lowercase, multiple words allowed, separated_by_underscores
method (private)	_lowercase, multiple words allowed, separated_by_underscores
variable (public)
variable (private)
constant	UPPER_CASE

Specific Guidelines

Executables

Scripts must be named according to the function they carry out.

# YES!
build_intermine.sh

# NO!
x

Scripts must have a suffix that denotes their type (BASH scripts: .sh, Perl scripts: .pl, Ruby scripts: .rb).

# YES!
get_gene_ontology.pl

# NO!
build_db

Variables

Variable names should reflect the content of the variable. Be appropriately verbose so that the variable contents are clear.

Abbreviations and acronyms should be UPPERCASE when used as a name:

print_HTML();

CSS variable names SHOULD follow the same conventions as public class variables.

Private class variables should be written using lowercase with a preceding underscore):

sub _my_private_function {
   my ($self,@args) = @_;
   ...
}

Variables with a large scope SHOULD have globally unambiguous names; ambiguity MAY be distinguished by module membership. Variables with small or private scope MAY have terse names.

Public names SHOULD be as clear as necessary and SHOULD avoid unclear shortenings and contractions:

get_BLAST_hits

NOT

gbh();

Iterator variables SHOULD be called "i", "j", "k", etc.

Abbreviations in names SHOULD be avoided.

Variables SHOULD be initialized where they are declared and they SHOULD be declared in the smallest scope possible. A null initialization is acceptable.

Variables MUST never have a dual meaning.

Related variables of the same type CAN be declared in a common statement; unrelated variables SHOULD NOT be declared in the same statement.

Variables SHOULD be kept alive for as short a time as possible.

Hash keys are unquoted unless absolutely necessary. If quotes are necessary, you should change your hash key.

# YES!
$hash{carrot} = 'orange';

# NO!
$hash{'carrot'} = 'orange';

Files

Class or object-per-file guidelines are not yet determined.

Tabs (set to 4 spaces) SHOULD be used for indentation.

Loops / iterative declarations

Only loop control statements MUST be included in the "for" loop construction.

Conditionals

Complex conditional expressions SHOULD be avoided; use temporary boolean variables instead.

The nominal case SHOULD be put in the "if" part and the exception in the "else" part of an "if" statement.

Layout

Function braces

Function braces begin on the line with their operator, and end on their own line indented to the same level.

foreach my $gene (@genes) {
      print "$gene\n";
                         }

# YES!
if (@genes) {
    print join("\n",@genes);
} else {
   print "We don't have any genes!\n";
}

# NO!
if (@genes)
{
    print join("\n",@genes);
} 
else {
   print "We don't have any genes!\n";
}

Additional examples follow:

Block statements.

Block layout SHOULD BE as illustrated below:

foreach (@items) {
    doSomething($_);
}

if statements SHOULD have the following form:

if (someCondition) {
    statements;
} elseif (someOtherCondition) {
    statements;
} else {
    statements;
}

for statements SHOULD have the following form:

for (initialization; condition; update) {
    statements;
}

A single statement if-else, while or for MUST NOT be written without brackets, but CAN be written on the same line:

if (condition) { statement; }
while (condition) { statement; }
for (intialization; condition; update){ statement; }

if/unless

conditionals CAN follow the test condition:

print @genes if (@genes > 10);

Whitespace

Conventional operators SHOULD be surrounded by a space (including ternary operators). Excess carriage returns SHOULD NOT be used around braces.

# YES!
sub my_function {
   my ($self,@args) = @_;
   
   my $string = join(" ", @args) . ': this is an inane example.';
   return $string;
}

# NO!
sub my_function {
   my($self,@args)=@_;
   
  # Hard to read these lines without space between operators...

   my $string=join(" ", @args).': this is an inane example.';

   return $string;   
   # Why are there carriage returns below here and closing brace? Not necessary.

}

In addition:

Commas SHOULD be followed by a space.

Colons MAY be surrounded by a space.

Semi-colons in for statements SHOULD be followed by a space.

Semi-colons SHOULD NOT be preceded by a space.

Function calls and method calls SHOULD NOT be followed by a space. Example: do_something(arguments); // NOT do_something (arguments)

Statements and declarations SHOULD be aligned wherever this enhances readability.

Comments

Tricky code SHOULD not be commented, but rewritten.

All comments SHOULD be written in English.

Comments SHOULD be indented relative to their position in the code, preceding or to the right of the code in question.

Comments SHOULD be included to explain BLOCKS of code, to explain the point of the following block.

Comments SHOULD NOT be included for every single line of code.

User Interface

Widget and field names

Widget and field names are specified in the application configuration. Since these names auto-vivify to actions -- and map to templates of the same name -- choose them carefully. Likewise, editing them requires changing the name of the template on the file system, too.

Widget names should preferably be short - a single word, and no more than three words. Field names can be more descriptive but no longer than five words.

Default widgets and fields

Identification

Each class should implement a default "Identification" widget. This widget is intended to provide the basic information about a given object. This replaces our non-standard use of Identification, General Information, or General Info in the old structure.

Each Identification widget should minimally include name and common_name. You need only include these fields in the configuration file - they will become automatically available to the appropriate controller. Over-ride common_name in the appropriate model to return the most appropriate common name for an object.

Documentation

Coding standards

Contents