Coding style
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
- Generic:
- For emacs:
- For vi[m]:
- For Sublime Text:
- For Node.js:
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
- jQuery's "JavaScript Style Guide". Very complete.
- Sencha's "Javascript Code Style Guide with examples".
- Douglas Crockford's "The Elements of JavaScript Style", part 1 and part 2. Very old!
- GitHub's JS coding style. Too terse. Also weird, ie no semicolons…
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
andFALSE
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.