Difference between revisions of "Coding standards"

From WormBaseWiki
Jump to navigationJump to search
Line 5: Line 5:
 
== Indentation ==
 
== Indentation ==
  
== Variable names ==
+
= WormBase Coding Standards and Style Guide =
  
  
 +
== Quick Reference ==
  
 +
Formatting conventions
  
 +
{|table border=1
 +
!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
 +
|-
 +
|}
  
  
WormBase Coding Standards and Style Guide
 
 
Contents:
 
General
 
Quick Reference
 
Naming Conventions
 
Specific Naming Conventions
 
Files
 
Variables
 
Layout
 
Documentation
 
This document follows the basic outline of the Java Programming Conventions Guide, a copy of which may be found at http://geosoft.no/javastyle.html.
 
 
General
 
Any violation to this guide is allowed if it enhances readability.
 
 
Guidelines in this document are informed by discussions carried out among the Dojo core developers. The most weight has been given to considerations that impact external developer interaction with Dojo code and APIs. Rules such as whitespace placement are of a much lower order importance for Dojo developers, but should be followed in the main in order to improve developer coordination.
 
 
Quick Reference
 
Table of core API naming constructs:
 
 
Construct    Convention    Comment
 
module    lowercase    never multiple words
 
class    CamelCase   
 
public method    mixedCase    whether class or instance method. lower_case() is acceptable only if the particular function is mimicking another API.
 
public var    mixedCase   
 
constant    CamelCase or UPPER_CASE   
 
Table of constructs that are not visible in the API, and therefore carry less weight of enforcement.
 
 
Construct    Convention
 
private method    _mixedCase
 
private var    _mixedCase
 
method args    _mixedCase, mixedCase
 
local vars    _mixedCase, mixedCase
 
 
Naming Conventions
 
Naming Conventions
 
Names representing modules SHOULD be in all lower case.
 
Names representing modules SHOULD be in all lower case.

Revision as of 23:39, 9 February 2008

File and Directory Names

Code Formatting

Indentation

WormBase Coding Standards and Style Guide

Quick Reference

Formatting conventions

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


Naming Conventions Names representing modules SHOULD be in all lower case.

Names representing types (classes) MUST be nouns and written using CamelCase capitalization:

Account, EventHandler Constants SHOULD be placed within a single object created as a holder for constants, emulating an Enum; the enum SHOULD be named appropriately, and members SHOULD be named using either CamelCase or UPPER_CASE capitalization:

var NodeTypes = {

   Element : 1,
   DOCUMENT: 2

} Abbreviations and acronyms SHOULD NOT be UPPERCASE when used as a name:

getInnerHtml(), getXml(), XmlDocument Names representing methods SHOULD be verbs or verb phrases:

obj.getSomeValue() Public class variables MUST be written using mixedCase capitalization.

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

Private class variables MAY be written using _mixedCase (with preceding underscore):

var MyClass = function(){

   var _buffer;
   this.doSomething = function(){
   };

} Variables that are intended to be private, but are not closure bound, SHOULD be prepended with a "_" (underscore) char:

this._somePrivateVariable = statement; Note: the above variable also follows the convention for a private variable.

Generic variables SHOULD have the same name as their type:

setTopic(topic) // where topic is of type Topic All names SHOULD be written in English.

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.

The name of the return object is implicit, and SHOULD be avoided in a method name:

getHandler(); // NOT getEventHandler() Public names SHOULD be as clear as necessary and SHOULD avoid unclear shortenings and contractions:

MouseEventHandler, NOT MseEvtHdlr. Note that, again, any context that can be determined by module membership SHOULD be used when determining if a variable name is clear. For example, a class that represents a mouse event handler:

dojo.events.mouse.Handler // NOT dojo.events.mouse.MouseEventHandler Classes/constructors MAY be named based on their inheritance pattern, with the base class to the right of the name:

EventHandler UIEventHandler MouseEventHandler The base class CAN be dropped from a name if it is obviously implicit in the name:

MouseEventHandler as opposed to MouseUIEventHandler. Specific Naming Conventions The terms get/set SHOULD NOT used where a field is accessed, unless the variable being accessed is lexically private.

The "is" prefix SHOULD be used for boolean variables and methods. Alternatives include "has", "can" and "should"

The term "compute" CAN be used in methods where something is computed.

The term "find" CAN be used in methods where something is looked up.

The terms "initialize" or "init" CAN be used where an object or a concept is established.

UI Control variables SHOULD be suffixed by the control type. Examples: leftComboBox, topScrollPane

Plural form MUST be used to name collections.

A "num" prefix or "count" postfix SHOULD be used for variables representing a number of objects.

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

Complement names MUST be used for complement entities. Examples: get/set, add/remove, create/destroy, start/stop, insert/delete, begin/end, etc.

Abbreviations in names SHOULD be avoided.

Negated boolean variable names MUST be avoided:

isNotError, isNotFound are unacceptable. Exception classes SHOULD be suffixed with "Exception" or "Error" .. FIXME (trt) not sure about this?

Methods returning an object MAY be named after what they return, and methods returning void after what they do.

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

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

If your editor supports "file tags", please append the appropriate tag at the end of the file to enable others to effortlessly obey the correct indentation guidelines for that file:

// vim:ts=4:noet:tw=0: The incompleteness of a split line MUST be made obvious :

var someExpression = Expression1

   + Expression2
   + Expression3;

var o = someObject.get(

   Expression1,
   Expression2,
   Expression3

); Note the indentation for expression continuation is indented relative to the variable name, while indentation for parameters is relative to the method being called.

Note also the position of the parenthesis in the method call; positioning SHOULD be similar to the use of block notation.

Variables 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. Loops / iterative declarations Only loop control statements MUST be included in the "for" loop construction. Loop variables SHOULD be initialized immediately before the loop; loop variables in a "for" statement MAY be initialized in the "for" loop construction. The use of "do...while" loops is acceptable (unlike in Java). The use of "break" and "continue" is not discouraged (unlike in Java). 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. Executable statements in conditionals MUST be avoided. Miscellaneous The use of magic numbers in the code SHOULD be avoided; they SHOULD be declared using named "constants" instead. Floating point constants SHOULD ALWAYS be written with decimal point and at least one decimal. Floating point constants SHOULD ALWAYS be written with a digit before the decimal point. Layout Block statements.

Block layout SHOULD BE as illustrated below: while(!isDone){

   doSomething();
   isDone = moreToDo();

} if statements SHOULD have the following form:

if(someCondition){

   statements;

}else if(someOtherCondition){

   statements;

}else{

   statements;

} for statements SHOULD have the following form:

for(initialization; condition; update){

   statements;

} while statements SHOULD have the following form:

while(!isDone){

   doSomething();
   isDone = moreToDo();

} do...while statements SHOULD have the following form:

do{

   statements;

}while(condition); switch statements SHOULD have the following form:

switch(condition){ case ABC:

   statements;
   //  fallthrough

case DEF:

   statements;
   break;

default:

   statements;
   break;

} try...catch...finally statements SHOULD have the following form:

try{

   statements;

}catch(ex){

   statements;

}finally{

   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; } Whitespace

Conventional operators MAY be surrounded by a space (including ternary operators). The following reserved words SHOULD NOT be followed by a space: break catch continue do else finally for function if anonymous, ex. var foo = function(){}; if return switch this try void while with The following reserved words SHOULD be followed by a space: case default delete function if named, ex. function foo(){}; in instanceof new throw typeof var 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: doSomething(someParameter); // NOT doSomething (someParameter) Logical units within a block SHOULD be separated by one blank line. Statements MAY 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. The declaration of collection variables SHOULD be followed by a comment stating the common type of the elements in the collection. 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. Documentation stolen from: Jot wiki

General Information These provide descriptions for the function or object:

summary: A short statement of the purpose of the function or object description: An extended description of the function or object returns: A description of what the function returns (does not include a type) General Function Information function(){

 // summary: Soon we will have enough treasure to rule all of New Jersey.
 // description: Or we could just get a new roomate.
 //        Look, you go find him.  He don't yell at you.
 //        All I ever try to do is make him smile and sing around
 //        him and dance around him and he just lays into me.
 //        He told me to get in the freezer 'cause there was a carnival in there.
 // returns:  Look, a Bananarama tape!

} Object Function Information Has no description of what it returns {

 // summary: Dingle, engage the rainbow machine!
 // description: 
 //        Tell you what, I wish I was--oh my g--that beam,
 //        coming up like that, the speed, you might wanna adjust that.
 //        It really did a number on my back, there. I mean, and I don't
 //        wanna say whiplash, just yet, cause that's a little too far,
 //        but, you're insured, right?

} Function Assembler Information (defineWidget/declare) We can sometimes end up in situations where a function declaration is invisible, being created by the call. In this case, there's no way to associate our comments directly with the function. If you encouter this situation, the data can be associated through the passed object.

Note, this only works if there is no initializer function parameter. If there is, this will be ignored.

dojo.declare(

 "foo",
 null,
 {
   // summary: Phew, this sure is relaxing, Frylock.
   // description: 
   //        Thousands of years ago, before the dawn of
   //        man as we knew him, there was Sir Santa of Claus: an
   //        ape-like creature making crude and pointless toys out
   //        of dino-bones, hurling them at chimp-like creatures with
   //        crinkled hands regardless of how they behaved the
   //        previous year.
   // returns: Unless Carl pays tribute to the Elfin Elders in space.
 }

); Parameters Simple Types If you're only going to be describing the type of the object, you should do it in the main parameter definition block.

function(/*String*/ foo, /*int*/ bar)... Type Modifiers There are some modifiers you can add after the type ? means optional ... means the last parameter repeats indefinitely [] means an array function(/*String?*/ foo, /*int...*/ bar, /*String[]*/ baz)... Full Parameter Descriptions If you want to also add a description, you should move to the initial comment block.

The format for the general information is: *key *Descriptive sentence

The format for paramters and variables is: *key ~type~* Descriptive sentence

Where *key *and ~*type*~ can be surrounded by any non-alphanumeric characters.

function(foo, bar){

 // foo: String
 //        used for being the first parameter
 // bar: int
 //        used for being the second parameter

} Variables Instance variables, prototype variables and external variables can all be defined in the same way. There are many ways that a variable might get assigned to this function, and locating them all inside of the actual function they reference is the best way to not lose track of them, or accidentally comment them multiple times. function foo(){

 // myString: String
 // times: int
 //        How many times to print myString
 // separator: String
 //        What to print out in between myString*
 this.myString = "placeholder text";
 this.times = 5;

} foo.prototype.setString = function(myString){

 this.myString = myString;

} foo.prototype.toString = function(){

 for(int i = 0; i < this.times; i++){
   dojo.debug(this.myString);
   dojo.debug(foo.separator);
 }

} foo.separator = "====="; Variable Comments in an Object The parser takes the comments in between object values and applies the same rules as if they were in the initial comment block: {

 // key: String
 //        A simple value
 key: "value",
 // key2: String
 //        Another simple value

} Return Value Because a function can return multiple types, the types should be declared on the same line as the return statement, and the comment must be the last thing on the line. If all the return types are the same, the parser uses that return type. If they're different, the function is considered to return "mixed".

function(){

 if(arguments.length){
   return "You passed argument(s)"; // String
 }else{
   return false; // Boolean
 }

} Still Up for Discussion Pseudo-Code (implemented)

There are some instances where you might want an object or function to appear in documentation, but not in Dojo, nor in your build. To do this, start a comment block with /*=====. The number of = can be 5 or more. At the moment, this is only useful for declaring an object type that doesn't appear in code.

The parser simply replaces the /*===== and =====*/ with whitespace at the very start, so think of these blocks as if they were commented out.

/*===== module.pseudo.kwArgs = {

 // url: String
 //        The location of the file
 url: "",
 // mimeType: String
 //        text/html, text/xml, etc
 mimeType: ""

} =====*/

function(/*module.pseudo.kwArgs*/ kwArgs){

 dojo.debug(kwArgs.url);
 dojo.debug(kwArgs.mimeType);

} Using the Doctool locally If you are a developer who has marked their code up using this syntax and want to test to make sure it is correct, you can run the doctool yourself locally. See DocParserInstructions for details on how to do so.