Home

Language Specific Standards

• PHP Code Standards
• Javascript Code Standards
• CSS Code Standards

---

General Code Standards

Comments

• Use /** ... */ for multiline comments. Include a description, specify types and values for all parameters and return values.

   // bad
   // make() returns a new element
   // based on the passed in tag name
   //
   // @param <String> tag
   // @return <Element> element
   function make(tag) {
  
   	// ...stuff...
  
   	return element;
   }
  
   // good
   /**
    * make() returns a new element
    * based on the passed in tag name
    *
    * @param <String> tag
    * @return <Element> element
    */
   function make(tag) {
  
   	// ...stuff...
  
   	return element;
   }

• Use // for single line comments. Place single line comments on a newline above the subject of the comment. Put an empty line before the comment.

   // bad
   var active = true;	// is current tab
  
   // good
   // is current tab
   var active = true;
  
   // bad
   function getType() {
   	console.log('fetching type...');
   	// set the default type to 'no type'
   	var type = this._type || 'no type';
  
   	return type;
   }
  
   // good
   function getType() {
   	console.log('fetching type...');
  
   	// set the default type to 'no type'
   	var type = this._type || 'no type';
  
   	return type;
   }

• Prefixing your comments with FIXME or TODO helps other developers quickly understand if you're pointing out a problem that needs to be revisited, or if you're suggesting a solution to the problem that needs to be implemented. These are different than regular comments because they are actionable. The actions are FIXME -- need to figure this out or TODO -- need to implement.

• Use // FIXME: to annotate problems

   function Calculator() {
  
   	// FIXME: shouldn't use a global here
   	total = 0;
  
   	return this;
   }

• Use // TODO: to annotate solutions to problems

   function Calculator() {
  
   	// TODO: total should be configurable by an options param
   	this.total = 0;
  
   	return this;
   }