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.
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.sites.models import Site
from django.db import models
from django.db.models import Q
from django.db.models.signals import post_save
from tastypie.models import ApiKey
from pootle_language.models import Language
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:
objects
managerclass Meta
def natural_key()
(Because it is tightly related to model fields)@classmethod
def __unicode__()
def __str__()
__
(for example __init__()
)def save()
def delete()
def get_absolute_url()
def get_translate_url()
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:
url()
function, not a tuple.pootle-{app}-{view}
(except in some
specific cases):{app}
is the app name, which sometimes can be shortened, e.g. using
tp to avoid the longish translationproject. The chosen app name
must be used consistently across all the URL patterns for the app.{view}
is a unique string which might consist on several words,
separated with hyphens, that might not match the name of the view that is
handled by the URL pattern.pootle-xhr-{view}
.pootle-admin-{view}
pootle-{view}
.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'),
)
In order to have a more consistent code the use of specific names for some heavily used variables is encouraged:
ctx
: Name for the dictionary with the context passed to a template for
rendering. Also known as context, template variables or template vars.
# Good.
ctx = {
'language': language,
}
# Bad.
context = {
...
templatevars = {
...
template_vars = {
...
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:: POOTLE_TITLE
To link to a setting, use :setting:`POOTLE_TITLE`
.
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.
Pootle and Django commands:
.. django-admin:: sync_stores
To link to a command, use :djadmin:`sync_stores
Follow the great Airbnb JavaScript Style Guide. Go check it out for all the details.
As a summary, that includes:
pascalCase
variable naming.In addition to that:
When dealing with existing or legacy code, also keep in mind to:
$
Variables holding jQuery objects.js-
to prefix selectors for elements queried via JavaScript.For React + JSX code also follow the Airbnb React/JSX Style Guide, with the following exceptions:
.js
extension for React components (not .jsx
).React.createClass({})
over extending React.Component
.Also bear in mind the following:
handle*()
for methods, on*()
for props.propTypes
: sort them alphabetically, but also group them to place
isRequired
types first.Always use double quotes for HTML attribute values.
Always use single quotes for Django template tags and template filters located inside HTML attribute values.
<!-- Good -->
<a href="{% url 'whatever' %}" class="highlight">
Good:
.foo-bar,
.foo-bar:hover
{
background-color: #eee;
}
Bad:
.foo-bar, .foo-bar:hover {
background-color: #eee;
}
.tm-results
and not
.TM_results
.