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.
Pootle-specific markup
For documenting several things, Pootle defines custom Sphinx roles.
Settings:
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.