Coding style guide

test

Introduction

The 2 most used languages at Code Yellow are

  1. PHP
  2. Javascript

PHP has PHP-FIG which is becoming more commenly accepted. Javascript has idiomatic. For all projects we apply these rules:

General

  • First check:

    1. PSR-1
    2. PSR-2
  • Use single quotes for strings where possible:

    • PHP $stringA = ‘this is a string’; $stringB = ‘this is another string ’ . $blah . ‘ test’;
    • Javascript var stringA = ‘this is a string’, stringB = ‘this is a string ’ + blah + ‘ test’;
  • First start with properties, then functions.

  • Prefix variables with class type where possible. Uppercase letters are classes, lowercase objects. The available prefixes are

    • M, m for model
    • V, v for view
    • T for template
    • X for mixin ```php <?php // PHP $mPerson = new \Model_Person();

    class SomeSpecialClass { private $MPerson = ‘\Model_Person’; private $mPerson = null;

    public function __construct(\Model_Person $mPerson = null) 
    {
        if ($mPerson === null) {
            $this->mPerson = $mPerson;
        } else {
            $this->mPerson = new $this->MPerson();
        }
    }
    
    // Strict camelCase.
    public function parseRestHttp() 
    {
        // Do something.
    }
    

    }

    ```javascript
    // Javascript
    var MPerson = require('model/person'),
    mPerson = new MPerson();
    

Javascript

Idiomatic with adjustments. Check out backbone-crux for an example on how to implement the style guide in Javascript.

  • Whitespace

    • Never mix spaces and tabs.
    • 4 spaces for indents
  • Parens, Braces, Linebreaks

        if (condition) {
            doSomething();
        }

        while (condition) {
            iterating++;
        }

        for (i = 0; i < 100; i++) {
            someIterativeFn();
        }
  • Using only one var per scope (function) promotes readability and keeps your declaration list free of clutter (also saves a few keystrokes). javascript var foo = 'bar', bar = '', array = [], object = {}; quux;
  • var statements should always be in the beginning of their respective scope (function). Same goes for const and let from ECMAScript 6.

        function foo(arg1, argN) {
            var bar = '',
            qux;
    
            // All statements after the variables declarations.
            require('someModule');
        }
  • Usage.

        foo(arg1, argN);
  • Named Function Declaration.

        function square(number) {
            return number * number;
        }
  • Usage.

        square(10);
  • Really contrived continuation passing style.

        function square(number, callback) {
            callback(number * number);
        }
    
        square(10, function (square) {
            // callback statements
        });
  • Function Expression

        var square = function (number) {
            // Return something valuable and relevant
            return number * number;
        };
  • Function Expression with Identifier. This preferred form has the added value of being able to call itself and have an identity in stack traces.

        var factorial = function factorial (number) {
            if (number < 2) {
                return 1;
            }
    
            return number * factorial(number - 1);
        };
  • Constructor Declaration

        function FooBar(options) {
            this.options = options;
        }
  • Usage.

        var fooBar = new FooBar({a: 'alpha'});
    
        fooBar.options;
  • Functions with callbacks.

        foo(function () {
        });
    
        foo(['alpha']);
        foo(['alpha', 'beta']);
        foo([
            'alpha', 
            'beta', 
            'gamma'
        ]);
    
        foo({a: 'alpha'});
    
        foo({
            a: 'alpha',
            b: 'beta'
        });
    
        foo('bar');
  • Where possible, be concise.

    // Instead of...
    if (array.length > 0) ...
    if (array.length === 0) ...
    if (string !== '') ...
    if (string === '') ...
    if (foo === true) ...
    if (foo === false) ...
        
    // ...use
    if (array.length) ...
    if (!array.length) ...
    if (string) ...
    if (!string) ...
    if (foo) ...
    if (!foo) ...
    
    // Be careful, this will also match: 0, '', null, undefined, NaN
    // If you _MUST_ test for a boolean false, then use
    if (foo === false) ...
    
    // When only evaluating a ref that might be null or undefined, but NOT false, "" or 0,
    // instead of this:
    if (foo === null || foo === undefined) ...
    
    // ...take advantage of == type coercion, like this:
    if (foo == null) ...
    
    // Remember, using == will match a `null` to BOTH `null` and `undefined`
    // but not `false`, "" or 0
    null == undefined
  • ALWAYS evaluate for the best, most accurate result - the above is a guideline, not a dogma. Type coercion and evaluation notes. Prefer === over == (unless the case requires loose type evaluation) === does not coerce type, which means that:

    '1' === 1; // false
  • == does coerce type, which means that:

    '1' == 1; // true
  • ‘Namespace’ with colon:

    vent.trigger('nav:open');
    vent.trigger('nav:close');
  • Add wrappers before subject:

    vent.trigger('before:nav:close');
    vent.trigger('after:nav:close');
  • Camelcase:

    'slideToggle'
    'before:slideToggle'
    'after:slideToggle'
  • Prefixe models, collections, views, regions and mixins as follows:

    // Class:
    var MAccount = require('model/account'),
    CAccount = require('collection/account'),
    VAccount = require('view/account'),
    RDialog = require('region/dialog'),
    XAccount = require('mixin/account'),
    
    // Instance of class:
    mAccount = new MAccount(),
    cAccount = new CAccount(),
    vAccount = new VAccount(),
    xAccount = new XAccount()
  • File header:

    // # Some awesome code title
    //
    // ### _Subtitle._
    //
    // Amazing description of code.
    // ___
    //
    // **Author:** AB Zainuddin
    //
    // **Email:** burhan@codeyellow.nl
    //
    // **Website:** 
    //
    // **License:** Not yet...
    // ___
  • Document functions with PHPDoc/JSDoc.

  • Always ‘use strict’;

  • Comment above lines.

  • Use these settings for .jshintrc: ```javascript { “globals”: { // RequireJS “require”: true, “define”: true, “module”: true,

        // Jasmin.
        "using": true,
        "expect": true,
        "it": true,
        "describe": true,
        "waitsFor": true,
        "runs": true,
        "jasmine": true,
        "beforeEach": true,
        "mostRecentAjaxRequest": true
    },
    "onecase": true,
    "quotmark": "single",
    "unused": "vars",
    "strict": true,
    "undef": true,
    "trailing": true,
    "browser": true
    

    }

# Frontend project layout

- Use camelCase for file names.

- Put template in same folder as Javascript file
    - search.html
    - search.js

- If a file uses other files, put it in a same named folder. Example:
    - search.html
    - search.js
    - search/
        - result/
            - item.html
            - item.js
        - pager.html
        - pager.js
        - result.html
        - result.js

- Use _ prefix for system folders.
    - view/
        - _common/
            - search.js
        - user/
            - overview.js (<-- uses _common/search.js)

- Route / convert to : events.
    - user/overview
    - user:overview

    - user/create
    - user:create

    - user/edit/:id
    - user:edit

- Routes map to files in view folder where possible.
    - user/overview
    - user/overview.js

    - user/create
    - user/create.js

    - user/edit
    - user/edit.js



# HTML

- Prefix elemenets required by app with with an underscore.
- Use double quotes for attribute values.
- Suffixed region DOM-element selectors with '-region'.
- Classname seperatered with '-'.
- Avoid using ids.

```html
<div id="_body"></div>
<div class="_some-important-element"></div>
<div class="_product-region"></div>
Tags// , ,