Pootle developers try to stick to some development standards that are gathered in this document.
For Python code and documentation Pootle follows the Translate Styleguide adding extra clarifications listed below.
Pootle has specific conventions for Python coding style.
Like in Python import conventions in Translate styleguide, but imports should be grouped in the following order:
Check Python import conventions in Translate styleguide for other conventions that the imports must follow.
from __future__ import absolute_import
import re
import sys.path as sys_path
import time
from datetime import timedelta
from os import path
from lxml.html import fromstring
from translate.storage import versioncontrol
from django.contrib.auth.models import User
from django.db import models
from django.db.models import Q
from django.db.models.signals import post_save
from profiles.views import edit_profile
from tastypie import fields
from pootle.core.decorators import permission_required
from pootle_store.models import (FUZZY, TRANSLATED, UNTRANSLATED, Store,
Unit, count_words)
from pootle_translationproject.models import TranslationProject
from .forms import GoalForm
from .models import Tag
Model’s inner classes and methods should keep the following order:
class SampleForm(forms.Form):
# Field declaration that spans to several lines.
language = forms.ChoiceField(
label=_('Interface Language'),
initial="",
required=False,
widget=forms.Select(attrs={
'class': 'js-select2 select2-language',
}),
help_text=_('Default language for using on the user interface.'),
)
# One line field declaration.
project = forms.ModelChoiceField(Project, required=True)
When writing the URL patterns:
urlpatterns = patterns('pootle_project.views',
# Listing of all projects.
url(r'^$',
'projects_index'),
# Whatever URLs.
url(r'^incredibly-stupid/randomly-long-url-with-hyphens-that-is-split-'
r'and-continued-on-next-line.html$',
'whatever',
name='pootle-project-whatever'),
# Admin URLs.
url(r'^(?P<project_code>[^/]*)/admin.html$',
'project_admin'),
url(r'^(?P<project_code>[^/]*)/permissions.html$',
'project_admin_permissions',
name='pootle-project-admin-permissions'),
)
Pootle specific settings must be named like POOTLE_*, for example: POOTLE_ENABLE_API, POOTLE_VCS_DIRECTORY or POOTLE_MARKUP_FILTER
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 were referring to an icon 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.
There are no “official” coding style guidelines for JavaScript, so based on several recommendations (1, 2, 3) we try to stick to our preferences.
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');
Control statements such as if, for, or switch should follow these rules:
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
}
Good:
.foo-bar,
.foo-bar:hover
{
background-color: #eee;
-webkit-box-shadow: 0 1px 4px #d9d9d9;
-moz-box-shadow: 0 1px 4px #d9d9d9;
box-shadow: 0 1px 4px #d9d9d9;
}
Bad:
.foo-bar, .foo-bar:hover {
background-color: #eee;
-webkit-box-shadow: 0 1px 4px #d9d9d9;
-moz-box-shadow: 0 1px 4px #d9d9d9;
box-shadow: 0 1px 4px #d9d9d9;
}