Coding Standards

This document states the coding standards by which all Steamed Pears abide.

General

1. 80 character line limit

2. Indent 2 spaces -- no tabs

3. Essentially whole-file indentation is discretionary.

4. Include a vim modeline at the end of the file (within the last 5 lines)

5. /* vim: set softtabstop=2 shiftwidth=2 tabstop=8 expandtab textwidth=80: */

6. Include the licence info block at the top of the file (as near the top as possible, and in its own comment block, using the comment markers appropriate for the language):

    /* Copyright by Steamed Pears, 2013. For licensing information, 
       see the LICENCE file in the root directory of this project. */
   
    <!-- Copyright by Steamed Pears, 2013. For licensing information,
         see the LICENCE file in the root directory of this project. -->
   

HTML

1. Double quotes: <tag attr="blah"></tag>
2. Lower case
3. Conform to HTML5
4. Use non-XML style: <br>

Refer to CSS for id and class naming standards

JavaScript

1. Single quotes: foo('bar')

2. No spaces before and after attributes within parentheses: function (x) {

3. Curly braces on their opening line: function() {

4. Unquoted keys in objects: {foo:'bar'}

5. Use JSHint

6. No fancy ExpressJS style comma first continuations

7. Declare var statements whenever you need a new variable. Not just one var statement per function up top.

8. In argument lists and array literals, a space following commas: (arg1, arg2, arg3)

9. Spaces around all (symbolic, non-unary) operators: 1 + 2 * 3, cond ? truePart : falsePart, x = y, etc.

10. Space following the function keyword iff the function is anonymous: function (arg) {...} but function foo(arg) {...}

11. Space following control structure keywords: switch (cond), if (cond), while (cond), etc.

12. Space preceding the brace opening a block: if (cond) {

13. Name methods with the constructor name, an underscore, and the function name:

     function MyConstructor(args) {...};
     MyConstructor.prototype = {
       method: function MyConstructor_method(args) {...}
     }
    

14. In object literals and case statements, space after : but not before.

15. if statements with one-line consequents should be all on one line or have braces.

16. If there's an else clause, just put in the braces.

17. else and else if on the same line as the } from the if.

18. Indent case to the same level as the enclosing switch; indent the body one level more.

CSS

1. Lower case: this-is-an-id
2. Use dashes for spaces in classes and ids: .this-is-a-class

Proposals

JavaScript

1. Comment boxes are used to visually partition script files, but they are only to be used outside of blocks of any kind. In other words, they should never be indented. The first line of a comment box is a forward slash followed by 77 asterisks, the last line is 77 asterisks followed by a forward slash. Every line in between begins with an asterisk, a space, a string (comment), then spaces up to the 77th character column, then a closing asterisk. Comment boxes are of the form:

    /******************************************************************************
    * Start the server                                                            *
    * Start the server                                                            *
    * Start the server                                                            *
    ******************************************************************************/
   

Bash Scripts

1. In bash scripts, comment headers will be like above, but with 78 hash symbols.

     ##############################################################################
     # Helper functions                                                           #
     ##############################################################################
   

2. The ISO8601 date string shall be acquired by the following command: date +%Y-%m-%dT%H%M%S%Z