A minimal JavaScript style guide intended to make reading and writing code easier.

styleguide.md

A Minimal JavaScript Style Guide

Written and Managed by Robbie Antenesse

As I'm working on JavaScript projects, I want to be sure that I have a consistent and readable style. This style guide is based partially on how I normally program anyway, partially on what I like from the ES2015 standard, and partially on what I think will help make any future code I write more readable to someone who might come after me.

This'll probably be changing infrequently as I find things I don't like about what I've decided or remember things that are missing.

Naming

• Names MUST BE verbose and represent the named thing well.
• Names MUST BE precise and specific.
  • If a name contains more than 3 or 4 words, the named thing MUST BE simplified and split into smaller pieces.

Patterns

• Classes MUST BE given a PascalCase namespace followed by an underscore before its PascalCase name: ProjectName_ClassName.
  • The namespace SHOULD BE the project name, though it MAY be shortened if desired (i.e. ProjectName_ -> PN_).
  • If a class extends another class, the extended class name SHOULD BE used as the namespace.
• Generic objects MUST BE PascalCase.
• Custom functions MUST BE camelCase() with no space before the arguments list.
  • When referring to a function, it MUST BE written with () suffixed to its name as above, regardless of any arguments.
• Variables MUST BE lowercase.
  • The MAY use underscores if multiple words are needed, but SHOULD only be one word.
  • Arrays are considered variables and SHOULD BE named as such, but for clarity, adding _array, _arr, or some other indicator as a suffix to the variable name MAY BE done if it helps you.
• Constants MUST BE ALLCAPS.

Spacing

• Spaces MUST surround operators. 1 + 2 = 3;
• Indents MUST BE 4 spaces.
• Indents MUST come on the line after an open brace {.
• Open braces MUST BE on the same line as its object's declaration unless the declaration is > 100 characters.
  • If the declaration is > 100 characters, then open brace is on the next line with the same indentation as above.
• Function declarations never have a space between the function name and the argument list.
  • Anonymous/unnamed functions are only used as arrow functions () => { return "hello"; }.
• Single-line functions like () => { return "hello"; } MUST have spaces after the open brace { and before the close brace }.
• All comma-separated lists (i.e. function arguments, arrays, etc.) MUST have spaces after a comma.
• Arrays never have spaces after the open bracket [ or before the close bracket ].
  • The above rule about array brackets also apply to function argument parentheses.

Styling

Strings

• Single characters or words for specifying something are surrounded with single quotes '@' 'test'.
• Multiple words or statements are surrounded with double quotes "This is a test".
• Long/multiline strings are surrounded with backticks `This is a very long string that explains something`.
  • Backticks are also used to implement ES2015's string templating: `My name is ${name}.`.

Objects

Here is an example of what an object should look like on creation.

let AnObject = {
    "name"              : "An Object",
    "value"             : 5,
    "longvariablename"  : "Wow that's so long!",
    "type"              : 'fake',
    "doSomething"       : () => { return 1 + 1; }
}

• Generic objects property names MUST BE surrounded by double quotes, according to JSON format, when first being declared.
  • After the object is initially declared, it's perfectly acceptable to reference properties with AnObject.name.
• Generic object property names SHOULD NOT contain spaces.
  • This is so you can reliably use the AnObject.name notation instead of AnObject['name'].
• Single-line generic object declarations MUST NOT be used.
  • Even if there is only one property, the braces MUST BE on separate lines and the properties indented appropriately.
• Spaces between the property name and the colon : MUST cause all colons in the object to line up.
• Only one space is used after a property's colon.

Global Variables

• Global variables SHOULD BE contained in a global object, preferrably named G.
  • Storing them outside of an object (i.e. within window) is acceptable, but not ideal.

Functions

• Single-line functions MAY be used.
• Arrow functions MUST use return within brackets to return a value.
  • Even though ES2015 does not require it, this makes it easier to know what's going on.
• Default values SHOULD BE used wherever possible!
• Named arrow functions MUST surround arguments with parentheses, even if there is only one. let sayHello = (name = "Nobody") => { return `Hey there, ${name}!`; }

Arrays

• If an array declaration extends beyond column 100 in the document, the array's objects MUST BE split and written in the same way that generic objects are written, with brackets on their own lines and each element indented and on its own line.
  • A multi-line array MAY BE styled into columns (i.e. multiple elements per line) if it is logical to do so.