Coding style

From W3C Wiki

Ongoing, collaborative quest to find common coding styles for every programming language or platform we use.

JavaScript

Rules

Indentation

  • Four spaces (no tabs).
  • Blank lines should be precisely that: blank lines — without spaces nor tabs.

Spaces

  • No trailing spaces.

Comments

Documentation comments
  • Ideally, one above every module, package, file, class or method.
  • Use tags that either JSDoc or YUIDoc understand.
 /**
  * Short description of this module, package, file, class or method (in a sentence, ending with colon).
  *
  * Long description, if necessary. Any number of sentences.
  * @beta
  * @param {number} depth - Preferred depth for recursion.
  */
Multi-line comments
Single-line comments

Variable declaration

Tools we use for formatting

Sample file

 /**
  * This is a documentation comment.
  *
  * Intended to be processed by either JSDoc [ http://usejsdoc.org/ ] or YUIDoc [ http://usejsdoc.org/ ].
  */
 
 // we can using this several variables declaration (by default in JSbeautifier)
 var foo1,
     foo2,
     foo3;
 // OR this (actually use in specberus)
 var foo1
 ,   foo2
 ,   foo3
 ;
 // OR this
 var foo1;
 var foo2;
 var foo3;
 
 var collection = (function() {
 
     // 4 spaces for indentation.
     var keys = [];
     var values = [];    // Trailing one-line comment (separated from the actual code with 4 spaces).
 
     var isLarger = (keys.length > values.length) ? true : false;
 
     return {
 
         get: function(key) {
 
             var at = keys.indexOf(key);
 
             if (at >= 0) {
                 return values[at];
             } else {
                 var foo = {key1: 'value', key2: 7};
                 return (foo['key1'] + (whatever && foo));
             }
         },
 
         set: function(key, value) {
 
             var at = keys.indexOf(key);
 
             if (at < 0) {
                 at = keys.length;
             }
 
             keys[at] = key;
             values[at] = value;
 
         },
 
         remove: function(key) {
 
             var at = keys.indexOf(key);
 
             if (at >= 0) {
                 keys.splice(at, 1);
                 values.splice(at, 1);
             }
 
         }
 
     };
 
 }());
 
 app.use(foo.bar('stuff'));
 
 /* Double quotes require two keystrokes (on some keyboards)! Simple quotes are quicker (and save toner ;)
    Also, I suspect we tend to print " more often than ' on our geeky outputs (and on debug lines),
    so by enclosing strings in single quotes, we don't need to escape double quotes. */
 
 thingy(process.env.PORT || 80);
 
 // EOF

References of style

PHP

Perl

NB: inherited from the old page StyleGuide (last edited in 2007).

Perltidy configuration for check

`-sbt=2 -bt=2 -pt=2 -ce -l=78 -i=2 -msc=1 -nwrs=".." -nwls=".."`

Not quite, but close... Need to find an "optimal" setting and apply it.

Perltidy should probably be used as a lint and the suggested changes applied selectively. Perl is in general too complex to be automatically formatted.

Indentation

  • Two spaces per TAB, and no hard TABs.
  • Blocks and braces align K&R style.
  • Use aligning agressively; including for datastructures and other delimited things.
  • Functions with long or complex argument lists can be aligned like a block.
&function(
    $long, $arg, $list
);


operands

  • Use and, and or when appropriate; && and || only when you need higher precedence.
  • Use single quotes ' by default, use double quotes " only when you intend for interpolation.
  • Use not unless you really really mean !.
  • In boolean comparisons, prefer the TRUE and FALSE constants over shortcut booleans.
    • This is to allow for future changes when simple variables are replaced with objects and overloading of the comparison operators.
  • Don't use $var = $var . 'string' if $var .= 'string' will do.

Random Uncategorized Draft Notes

  • Give modules an an explicit version number in use Module n.m; only if we absolutely need a specific minimum version of that module.
  • Give modules an empty import list use Module qw(); to prevent namespace pollution.
  • For random values to compare against, use constant FOO => 'bar'; instead of spreading hard coded values throughout if()s in the code or declaring a whole lot of global variables.
  • Gratuitous reuse of CPAN code through modules is good; don't be afraid of extra dependencies.
    • Be prepared to help patch or maintain those CPAN modules if we need it though.
    • Balance this against what we know to be available on common Linux distros and ActiveState PPM repos.
      • Last two Fedora Core is probably a good indication of what our target should be.
  • Comment each function and most blocks.
  • Don't be afraid of whitespace; between blocks and in comments etc.
  • No arbitrary limits if they can be avoided.
    • If you set a limit (whatever it is) make sure you trap it and give a friendly error message.
    • Assumption is the mother of all fuckups. HTTP doesn't have to live on port 80; or any other fixed port you've ever dreamed of.
  • Logical blocks of code get major headings like
###############################################################################
#### Block Title. #############################################################
###############################################################################
  • Major headings get 3 blank lines of leading whitespace.
  • Minor headings (e.g. a sub with its comment) get 2 lines of leading whitespace.
  • Normal, non-inline, comments and their code get 1 line of leading whitespace.