# Styleguide

Pootle developers try to stick to some development standards that are gathered in this document.

## Python and documentation

For Python code and documentation Pootle follows the Translate Styleguide.

- Python style conventions
- Documentation style conventions

### Pootle-specific markup

For documenting several things, Pootle defines custom Sphinx roles.

- Settings:

      .. setting:: PODIRECTORY

  To link to a setting, use `:setting:`PODIRECTORY``.

- Icons:

      Some reference to |icon:some-icon| in the text.

  This allows you to easily add inline images of icons used in Pootle. The icons are all files from `pootle/static/images/sprite`. If you where refering to an icon `edit.png` then you would use the syntax `|icon:icon-edit|`. The icon reference is always prefixed by `icon:` and the name of the icon is used without the extension.

  E.g. `|icon:icon-google-translate|` will insert this icon.

## JavaScript

There are no “official” coding style guidelines for JavaScript, so based on several recommendations (1, 2, 3) we try to stick to our preferences.

Indenting
  - We currently use 2-space indentation. Don’t use tabs.
  - Avoid lines longer than 80 characters. When a statement will not fit on a single line, it may be necessary to break it. Place the break after an operator, ideally after a comma.
Whitespace
  - If a function literal is anonymous, there should be one space between the word `function` and the `(` (left parenthesis).
  - In function calls, don’t use any space before the `(` (left parenthesis).
  - Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.
  - Each `;` (semicolon) in the control part of a `for` statement should be followed with a space.
  - Whitespace should follow every `,` (comma).
Naming

  - Variable and function names should always start by a lowercase letter and consequent words should be CamelCased. Never use underscores.

  - If a variable holds a jQuery object, prefix it by a dollar sign `$`. For example:

        var $fields = $(".js-search-fields");

Selectors
  - Prefix selectors that deal with JavaScript with `js-`. This way it’s clear the separation between class selectors that deal with presentation (CSS) and functionality (JavaScript).
  - Use the same naming criterion as with CSS selector names, ie, lowercase and consequent words separated by dashes.
Control statements

  Control statements such as `if`, `for`, or `switch` should follow these rules:

  - The enclosed statements should be indented.
  - The `{` (left curly brace) should be at the end of the line that begins the compound statement.
  - The `}` (right curly brace) should begin a line and be indented to align with the beginning of the line containing the matching `{` (left curly brace).
  - Braces should be used around all statements, even single statements, when they are part of a control structure, such as an `if` or `for` statement. This makes it easier to add statements without accidentally introducing bugs.
  - Should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.
Examples

  - `if` statements

        if (condition) {
          statements
        }

        if (condition) {
          statements
        } else {
          statements
        }

        if (condition) {
          statements
        } else if (condition) {
          statements
        } else {
          statements
        }

  - `for` statements

        for (initialization; condition; update) {
          statements;
        }

        for (variable in object) {
          if (condition) {
            statements
          }
        }

  - `switch` statements

        switch (condition) {
          case 1:
            statements
            break;

          case 2:
            statements
            break;

          default:
            statements
        }

## HTML

Indenting
  - Indent using 2 spaces. Don’t use tabs.
  - Although it’s desirable to avoid lines longer than 80 characters, most of the time the templating library doesn’t easily allow this. So try not to extend too much the line length.

## CSS

Indenting
  - Indent using 4 spaces. Don’t use tabs.
  - Put selectors and braces on their own lines.

  Good:

      .foo-bar,
      .foo-bar:hover
      {
          background-color: #eee;
      }

  Bad:

      .foo-bar, .foo-bar:hover {
        background-color: #eee;
      }

Naming
  - Selectors should all be in lowercase and consequent words should be separated using dashes. As an example, rather use `.tm-results` and not `.TM_results`.