Why do we need Coding Standards

A good application has to:

• to do its job well
• but also be easy to extend, maintain and debug

Editing unfamiliar code is easier when

• has a good layout
• it's easy to read
• and the complicated parts are succinctly described with comments

Getting started

• A project should have a consistent coding style

• The exact rules should be specified somewhere (document, wiki page)

Starting point for our coding standards:

• the default WebStorm formatting is pretty decent
• the jQuery coding standards
  http://contribute.jquery.org/style-guide/js/

Of course, with some amendments.

Readable code

General rule:

• think first about readability and then performance
• code becomes legacy as soon as you get up and get another cup of coffee

 

What makes code readable:

• indentation to mark control structures
• consistent naming conventions
• functions named in accordance with what they do
• complex structures are commented

Naming conventions

• namespaces should use lower case names
  • so we can differentiate from class names
• classes should always use Pascal case
  • use Pascal case only for classes or constructors
  • otherwise is hard to detect classes defined in unexpected places (like inner/private classes)
• functions should start with a verb, and use Camel case
• variables should be nouns, and use Camel case
• constants should be all upper case
  • ex: DEFAULT_PAGE_WIDTH
• name things verbosely, except for counters like i, j, k
  • makes the code more readable
  • don't worry about file size, minifiers will take care of that

Empty lines

• use empty lines to separate groups of related lines of code (like paragraphs)
• don't put an empty line after the start of a method declaration
• don't put an empty line at the start of a file
• put an empty line at the end of the file
  • because if the file gets concatenated, then it's easier to read when debugging
• don't use more than one empty line

Comments

• demonstrate clearly the function of the code
• short and concise

 

Don't commit commented code!

• don't keep old code, use git history
• if something was not completely implemented, let it fail, so you know you have to implement it
• to show all the configuration options of some method
  ∘ it's better to do the documentation inside the object offering the options

Comments

Don't commit commented code!

• people waste time wondering what the code does and why it was commented
• as the live code around it changes, the code in the comment becomes obsolete
• large comments clutter the code, you have to scroll more to get to the actual code

Removing code

• when removing code, remove all the usages of that code
• remove unreachable code
  • otherwise it confuses the developer reading your code later
• remove unused declarations of variables, methods and so on
  • otherwise people start wondering, and lose time
• when removing code, also remove related comments
  • same as above

Size Observations

Smaller is better:

• avoid big files
• classes ~ 300 lines
• functions ~ 20 lines

Structure

Classes:

• a file should be read top-down
• the methods should be declared after they are used
• this will pushes the higher level methods to the top of the class

 

Functions:

• the function name should describe accurately what it does
• extract complex conditions to separate functions
  • this will provide a better description for the conditions
  • code becomes self documenting
• try to name callbacks
  • easier to debug

Structure

• always use braces for control structures
• prefer if-else to the ternary operator ?
• use enums for grouping constants

LESS / CSS

• display the properties of a parent class before the definitions of its children
• order the classes to reflect the DOM structure or relationships
• order the properties
  • group the ones that are related, like:
    • width, height | position, top, bottom, right, left
  • use the box model for the order
    • margin, border, padding
  • use them in a consistent order, like they are defined in a short declaration
    • top, left, bottom, right
• use 0 with unit (needed for animations)
• avoid negative z-indexes