Skip to content
This repository has been archived by the owner on Feb 12, 2024. It is now read-only.

Flow Style Guide

Jump to bottom
David Hu edited this page Feb 24, 2014 · 3 revisions

In general, we abide by Google’s style guides and our own style guides inherit from them.

What’s the point of a style guide? It keeps code consistent, saves you the effort of making trivial decisions, follows best practices (avoids error-prone constructions), and makes all code look like it was written by one person (in theory).

Once you get used to a style set, it becomes very easy to read and understand all code of the same style.

For the most part, if you stick to the conventions of the surrounding code, you should be fine. Where the style guide conflicts with existing code, prefer the style guide. We have old code that don’t abide by some conventions because this style guide was written later.

General

  • 4-space indent in Python; 2-space indents everywhere else
  • No trailing whitespace
  • 80-character line limit (inherited from Google)
  • Double-indent continuation lines
  • Avoid checking in commented-out code (exceptions allowed where reasonable — for example, if a line is meant to be un-commented shortly after).
  • Non-trivial functions should have explanatory docstrings/JSDoc.
  • Try to avoid huge functions. If possible, break them up into reusable, logical helper functions that do one thing each.

Python

We try to follow PEP8 as much as possible: http://www.python.org/dev/peps/pep-0008/

Use single quotes.

Docstrings follow http://www.python.org/dev/peps/pep-0257/

Imports

All imports should be at the top of the file, separated (by blank lines) into three sections: system imports, third-party imports, and Flow-written imports. Each section should be sorted alphabetically. Only one import should be on each line.

JavaScript

If you're new to JS, there's a surprisingly large amount of gotchas that's easy to miss. I usually recommend http://bonsaiden.github.io/JavaScript-Garden/ as a quick intro to the quirks and Good Parts.

Naming

ClassNamesLikeThis
methodNamesLikeThis
variableNamesLikeThis
propertyNamesLikeThis
_privateMethodOrPropertyNamesLikeThis
SYMBOLIC_CONSTANTS_LIKE_THIS

Variables and properties referring to jQuery element objects are prefixed with $. Example:

var $target = $(e.currentTarget);

For-loops

Try to avoid using for-loops where possible, and instead write an equivalent statement using Underscore.js's functional collection helpers (eg. _.map, _.reduce, _.any, _.each, and so on). We try to avoid for-loops because JS only has function scope, and creating closures in a loop is a common mistake that leads to difficult-to-find bugs. Also, using _.each eliminates the need to do a hasOwnProperty check.

Equality

Always use ===, due to numerous oddities that come from type coercion. We deny the existence of == in JS. :)

Libraries

Note that we currently use all of the following JS utility libraries:

In general, see if what you're trying to do is supported by a library first before rolling your own implementation.

SASS

If you’re new to Sass, take 3 mins to look at http://sass-lang.com/guide

Nesting

Nesting is a good way to organize CSS classes that will always follow the same structure, and to group related classes/styles. However, try not to go overboard, and try to limit nesting to not more than four levels deep.

Variables

Use them! They're one of the most awesome things about these CSS processors. When you find yourself repeating a value, consolidate it into a variable. When you find yourself re-using colors or styles across different parts of the site, consolidate into _variables.scss. Gone are the days of manually adding paddings and widths (add them in Sass! Or, use box-sizing: border-box;).

Compass mixins

Instead of this monstrosity:

background: #1e5799; /* Old browsers */
background: -moz-linear-gradient(top,  #1e5799 0%, #7db9e8 100%); /* FF3.6+ */
background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#1e5799), color-stop(100%,#7db9e8)); /* Chrome,Safari4+ */
background: -webkit-linear-gradient(top,  #1e5799 0%,#7db9e8 100%); /* Chrome10+,Safari5.1+ */
background: -o-linear-gradient(top,  #1e5799 0%,#7db9e8 100%); /* Opera 11.10+ */
background: -ms-linear-gradient(top,  #1e5799 0%,#7db9e8 100%); /* IE10+ */
background: linear-gradient(to bottom,  #1e5799 0%,#7db9e8 100%); /* W3C */
filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#1e5799', endColorstr='#7db9e8',GradientType=0 ); /* IE6-9 */

Let Compass do the work for you:

@include background(linear-gradient(top, #1e5799, #7db9e8));

Also note there are some CSS styles that used to require vendor prefixes (eg. box-shadow, border-radius) that are now widely supported and don’t require vendor prefixes.

Clone this wiki locally