<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Translate Styleguide — Translate Toolkit 1.9.0 documentation</title>
<link rel="stylesheet" href="_static/basic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '1.9.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/bootstrap.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>
<link rel="top" title="Translate Toolkit 1.9.0 documentation" href="index.html" />
<link rel="next" title="Building" href="development/building.html" />
<link rel="prev" title="Quoting and Escaping" href="formats/quoting_and_escaping.html" />
</head>
<body>
<div id="navbar" class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container-fluid">
<a class="brand" href="index.html">Translate Toolkit</a>
<span class="navbar-text pull-left"><b>1.9.0</b></span>
<ul class="nav">
<li class="divider-vertical"></li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Site <b class="caret"></b></a>
<ul class="dropdown-menu globaltoc"><ul class="simple">
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="features.html">Features</a></li>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="commands/index.html">Converters</a></li>
<li class="toctree-l1"><a class="reference internal" href="commands/index.html#tools">Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="commands/index.html#scripts">Scripts</a></li>
<li class="toctree-l1"><a class="reference internal" href="guides/index.html">Use Cases</a></li>
<li class="toctree-l1"><a class="reference internal" href="formats/index.html">Supported formats</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="">Translate Styleguide</a></li>
<li class="toctree-l1"><a class="reference internal" href="#documentation">Documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="development/building.html">Building</a></li>
<li class="toctree-l1"><a class="reference internal" href="development/contributing.html">Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="development/developers.html">Translate Toolkit Developers Guide</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Important Changes</a></li>
<li class="toctree-l1"><a class="reference internal" href="history.html">History of the Translate Toolkit</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
</ul>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Page <b class="caret"></b></a>
<ul class="dropdown-menu localtoc"><ul>
<li><a class="reference internal" href="#">Translate Styleguide</a><ul>
<li><a class="reference internal" href="#general">General</a></li>
<li><a class="reference internal" href="#expressions-and-statements">Expressions and Statements</a></li>
<li><a class="reference internal" href="#naming-conventions">Naming Conventions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#documentation">Documentation</a><ul>
<li><a class="reference internal" href="#special-roles">Special roles</a></li>
<li><a class="reference internal" href="#docstrings">Docstrings</a></li>
<li><a class="reference internal" href="#comments">Comments</a></li>
</ul>
</li>
</ul>
</ul>
</li>
<li><a href="formats/quoting_and_escaping.html"
title="previous chapter">« Quoting and Escaping</a></li>
<li><a href="development/building.html"
title="next chapter">Building »</a></li>
</ul>
<form class="navbar-search pull-right" action="search.html" method="get">
<input type="text" name="q" placeholder="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</ul>
</div>
</div>
</div>
</div>
<div class="container content">
<div class="section" id="translate-styleguide">
<span id="styleguide"></span><h1>Translate Styleguide<a class="headerlink" href="#translate-styleguide" title="Permalink to this headline">¶</a></h1>
<p>The Translate styleguide is the styleguide for all Translate projects,
including Translate Toolkit, Pootle, Virtaal and others. Patches are required
to follow these guidelines.</p>
<p>This Styleguide follows <span class="target" id="index-0"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0008"><strong>PEP 8</strong></a> with some clarifications. It is based almost
verbatim on the <a class="reference external" href="http://flask.pocoo.org/docs/styleguide/">Flask Styleguide</a>.</p>
<div class="section" id="general">
<span id="styleguide-general"></span><h2>General<a class="headerlink" href="#general" title="Permalink to this headline">¶</a></h2>
<dl class="docutils">
<dt>Indentation:</dt>
<dd>4 real spaces, no tabs. Exceptions, modules that have copied into
the source that don’t follow this guideline.</dd>
<dt>Maximum line length:</dt>
<dd>79 characters with a soft limit for 84 if absolutely necessary. Try
to avoid too nested code by cleverly placing <cite>break</cite>, <cite>continue</cite> and
<cite>return</cite> statements.</dd>
<dt>Continuing long statements:</dt>
<dd><p class="first">To continue a statement you can use backslashes (preceeded by a space)
in which case you should align the next line with the last dot or
equal sign, or indent four spaces:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">MyModel</span><span class="o">.</span><span class="n">query</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">MyModel</span><span class="o">.</span><span class="n">scalar</span> <span class="o">></span> <span class="mi">120</span><span class="p">)</span> \
<span class="o">.</span><span class="n">order_by</span><span class="p">(</span><span class="n">MyModel</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">desc</span><span class="p">())</span> \
<span class="o">.</span><span class="n">limit</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
<span class="n">my_long_assignment</span> <span class="o">=</span> <span class="n">MyModel</span><span class="o">.</span><span class="n">query</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">MyModel</span><span class="o">.</span><span class="n">scalar</span> <span class="o">></span> <span class="mi">120</span><span class="p">)</span> \
<span class="o">.</span><span class="n">order_by</span><span class="p">(</span><span class="n">MyModel</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">desc</span><span class="p">())</span> \
<span class="o">.</span><span class="n">limit</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
<span class="n">this_is_a_very_long</span><span class="p">(</span><span class="n">function_call</span><span class="p">,</span> <span class="s">'with many parameters'</span><span class="p">)</span> \
<span class="o">.</span><span class="n">that_returns_an_object_with_an_attribute</span>
</pre></div>
</div>
<p>If you break in a statement with parentheses or braces, align to the
braces:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">this_is_a_very_long</span><span class="p">(</span><span class="n">function_call</span><span class="p">,</span> <span class="s">'with many parameters'</span><span class="p">,</span>
<span class="mi">23</span><span class="p">,</span> <span class="mi">42</span><span class="p">,</span> <span class="s">'and even more'</span><span class="p">)</span>
</pre></div>
</div>
<p>For lists or tuples with many items, break immediately after the
opening brace:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="n">items</span> <span class="o">=</span> <span class="p">[</span>
<span class="s">'this is the first'</span><span class="p">,</span> <span class="s">'set of items'</span><span class="p">,</span> <span class="s">'with more items'</span><span class="p">,</span>
<span class="s">'to come in this line'</span><span class="p">,</span> <span class="s">'like this'</span>
<span class="p">]</span>
</pre></div>
</div>
</dd>
<dt>Blank lines:</dt>
<dd><p class="first">Top level functions and classes are separated by two lines, everything
else by one. Do not use too many blank lines to separate logical
segments in code. Example:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">hello</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
<span class="k">print</span> <span class="s">'Hello </span><span class="si">%s</span><span class="s">!'</span> <span class="o">%</span> <span class="n">name</span>
<span class="k">def</span> <span class="nf">goodbye</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
<span class="k">print</span> <span class="s">'See you </span><span class="si">%s</span><span class="s">.'</span> <span class="o">%</span> <span class="n">name</span>
<span class="k">class</span> <span class="nc">MyClass</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="sd">"""This is a simple docstring"""</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>
<span class="k">def</span> <span class="nf">get_annoying_name</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">upper</span><span class="p">()</span> <span class="o">+</span> <span class="s">'!!!!111'</span>
</pre></div>
</div>
</dd>
</dl>
</div>
<div class="section" id="expressions-and-statements">
<h2>Expressions and Statements<a class="headerlink" href="#expressions-and-statements" title="Permalink to this headline">¶</a></h2>
<dl class="docutils">
<dt>General whitespace rules:</dt>
<dd><ul class="first simple">
<li>No whitespace for unary operators that are not words
(e.g.: <tt class="docutils literal"><span class="pre">-</span></tt>, <tt class="docutils literal"><span class="pre">~</span></tt> etc.) as well on the inner side of parentheses.</li>
<li>Whitespace is placed between binary operators.</li>
</ul>
<p>Good:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">exp</span> <span class="o">=</span> <span class="o">-</span><span class="mf">1.05</span>
<span class="n">value</span> <span class="o">=</span> <span class="p">(</span><span class="n">item_value</span> <span class="o">/</span> <span class="n">item_count</span><span class="p">)</span> <span class="o">*</span> <span class="n">offset</span> <span class="o">/</span> <span class="n">exp</span>
<span class="n">value</span> <span class="o">=</span> <span class="n">my_list</span><span class="p">[</span><span class="n">index</span><span class="p">]</span>
<span class="n">value</span> <span class="o">=</span> <span class="n">my_dict</span><span class="p">[</span><span class="s">'key'</span><span class="p">]</span>
</pre></div>
</div>
<p>Bad:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="n">exp</span> <span class="o">=</span> <span class="o">-</span> <span class="mf">1.05</span>
<span class="n">value</span> <span class="o">=</span> <span class="p">(</span> <span class="n">item_value</span> <span class="o">/</span> <span class="n">item_count</span> <span class="p">)</span> <span class="o">*</span> <span class="n">offset</span> <span class="o">/</span> <span class="n">exp</span>
<span class="n">value</span> <span class="o">=</span> <span class="p">(</span><span class="n">item_value</span><span class="o">/</span><span class="n">item_count</span><span class="p">)</span><span class="o">*</span><span class="n">offset</span><span class="o">/</span><span class="n">exp</span>
<span class="n">value</span><span class="o">=</span><span class="p">(</span> <span class="n">item_value</span><span class="o">/</span><span class="n">item_count</span> <span class="p">)</span> <span class="o">*</span> <span class="n">offset</span><span class="o">/</span><span class="n">exp</span>
<span class="n">value</span> <span class="o">=</span> <span class="n">my_list</span><span class="p">[</span> <span class="n">index</span> <span class="p">]</span>
<span class="n">value</span> <span class="o">=</span> <span class="n">my_dict</span> <span class="p">[</span><span class="s">'key'</span><span class="p">]</span>
</pre></div>
</div>
</dd>
<dt>Slice notation:</dt>
<dd><p class="first">While <span class="target" id="index-1"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0008"><strong>PEP 8</strong></a> calls for spaces around operators <tt class="docutils literal"><span class="pre">a</span> <span class="pre">=</span> <span class="pre">b</span> <span class="pre">+</span> <span class="pre">c</span></tt> this
results in flags when you use <tt class="docutils literal"><span class="pre">a[b+1:c-1]</span></tt> but would allow
the rather unreadable <tt class="docutils literal"><span class="pre">a[b</span> <span class="pre">+</span> <span class="pre">1:c</span> <span class="pre">-</span> <span class="pre">1]</span></tt> to pass. <span class="target" id="index-2"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0008"><strong>PEP 8</strong></a> is
rather quiet on slice notation.</p>
<ul class="simple">
<li>Don’t use spaces with simple variables or numbers</li>
<li>Use brackets for expressions with spaces between binary operators</li>
</ul>
<p>Good:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">a</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="mi">2</span><span class="p">]</span>
<span class="n">a</span><span class="p">[</span><span class="n">start</span><span class="p">:</span><span class="n">end</span><span class="p">]</span>
<span class="n">a</span><span class="p">[(</span><span class="n">start</span> <span class="o">-</span> <span class="mi">1</span><span class="p">):(</span><span class="n">end</span> <span class="o">+</span> <span class="n">var</span> <span class="o">+</span> <span class="mi">2</span><span class="p">)]</span> <span class="c"># Brackets help group things and don't hide the slice</span>
<span class="n">a</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">:(</span><span class="n">end</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)]</span>
</pre></div>
</div>
<p>Bad:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="n">a</span><span class="p">[</span><span class="n">start</span><span class="p">:</span> <span class="n">end</span><span class="p">]</span> <span class="c"># No spaces around :</span>
<span class="n">a</span><span class="p">[</span><span class="n">start</span><span class="o">-</span><span class="mi">1</span><span class="p">:</span><span class="n">end</span><span class="o">+</span><span class="n">var</span><span class="o">+</span><span class="mi">2</span><span class="p">]</span> <span class="c"># Insanely hard to read, especially when your expressions are more complex</span>
<span class="n">a</span><span class="p">[</span><span class="n">start</span> <span class="o">-</span> <span class="mi">1</span><span class="p">:</span><span class="n">end</span> <span class="o">+</span> <span class="mi">2</span><span class="p">]</span> <span class="c"># You lose sight of the fact that it is a slice</span>
<span class="n">a</span><span class="p">[</span><span class="o">-</span> <span class="mi">1</span><span class="p">:</span><span class="n">end</span><span class="p">]</span> <span class="c"># -1 is unary, no space</span>
</pre></div>
</div>
</dd>
</dl>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">String slice formating is still under discussion.</p>
</div>
<dl class="docutils">
<dt>Comparisons:</dt>
<dd><ul class="first last simple">
<li>against arbitrary types: <tt class="docutils literal"><span class="pre">==</span></tt> and <tt class="docutils literal"><span class="pre">!=</span></tt></li>
<li>against singletons with <tt class="docutils literal"><span class="pre">is</span></tt> and <tt class="docutils literal"><span class="pre">is</span> <span class="pre">not</span></tt> (eg: <tt class="docutils literal"><span class="pre">foo</span> <span class="pre">is</span> <span class="pre">not</span>
<span class="pre">None</span></tt>)</li>
<li>never compare something with <cite>True</cite> or <cite>False</cite> (for example never
do <tt class="docutils literal"><span class="pre">foo</span> <span class="pre">==</span> <span class="pre">False</span></tt>, do <tt class="docutils literal"><span class="pre">not</span> <span class="pre">foo</span></tt> instead)</li>
</ul>
</dd>
<dt>Negated containment checks:</dt>
<dd>use <tt class="docutils literal"><span class="pre">foo</span> <span class="pre">not</span> <span class="pre">in</span> <span class="pre">bar</span></tt> instead of <tt class="docutils literal"><span class="pre">not</span> <span class="pre">foo</span> <span class="pre">in</span> <span class="pre">bar</span></tt></dd>
<dt>Instance checks:</dt>
<dd><tt class="docutils literal"><span class="pre">isinstance(a,</span> <span class="pre">C)</span></tt> instead of <tt class="docutils literal"><span class="pre">type(A)</span> <span class="pre">is</span> <span class="pre">C</span></tt>, but try to avoid
instance checks in general. Check for features.</dd>
<dt>If statements:</dt>
<dd><ul class="first simple">
<li>Use <tt class="docutils literal"><span class="pre">()</span></tt> brackets around complex if statements to allow easy wrapping,
don’t use backslash to wrap an if statements.</li>
<li>Wrap between <tt class="docutils literal"><span class="pre">and</span></tt>, <tt class="docutils literal"><span class="pre">or</span></tt>, etc.</li>
<li>Keep <tt class="docutils literal"><span class="pre">not</span></tt> with the expression</li>
<li>Use <tt class="docutils literal"><span class="pre">()</span></tt> alignment between expressions</li>
<li>Use extra <tt class="docutils literal"><span class="pre">()</span></tt> to eliminate abiguity, don’t rely on an understanding of
Python operator precedent rules.</li>
</ul>
<p>Good:</p>
<div class="highlight-python"><pre>if length >= (upper + 2)
if (length >= 25 and
string != "Something" and
not careful):
do_something()</pre>
</div>
<p>Bad:</p>
<div class="last highlight-python"><pre>if length >= upper + 2:
if (length...
and string !=...</pre>
</div>
</dd>
</dl>
</div>
<div class="section" id="naming-conventions">
<h2>Naming Conventions<a class="headerlink" href="#naming-conventions" title="Permalink to this headline">¶</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This has not been implemented or discussed. The Translate code
is not at all consistent with these conventions.</p>
</div>
<ul class="simple">
<li>Class names: <tt class="docutils literal"><span class="pre">CamelCase</span></tt>, with acronyms kept uppercase (<tt class="docutils literal"><span class="pre">HTTPWriter</span></tt> and
not <tt class="docutils literal"><span class="pre">HttpWriter</span></tt>)</li>
<li>Variable names: <tt class="docutils literal"><span class="pre">lowercase_with_underscores</span></tt></li>
<li>Method and function names: <tt class="docutils literal"><span class="pre">lowercase_with_underscores</span></tt></li>
<li>Constants: <tt class="docutils literal"><span class="pre">UPPERCASE_WITH_UNDERSCORES</span></tt></li>
<li>precompiled regular expressions: <tt class="docutils literal"><span class="pre">name_re</span></tt></li>
</ul>
<p>Protected members are prefixed with a single underscore. Double underscores
are reserved for mixin classes.</p>
<p>On classes with keywords, trailing underscores are appended. Clashes with
builtins are allowed and <strong>must not</strong> be resolved by appending an underline to
the variable name. If the function needs to access a shadowed builtin, rebind
the builtin to a different name instead.</p>
<dl class="docutils">
<dt>Function and method arguments:</dt>
<dd><ul class="first last simple">
<li>class methods: <tt class="docutils literal"><span class="pre">cls</span></tt> as first parameter</li>
<li>instance methods: <tt class="docutils literal"><span class="pre">self</span></tt> as first parameter</li>
<li>lambdas for properties might have the first parameter replaced with <tt class="docutils literal"><span class="pre">x</span></tt>
like in <tt class="docutils literal"><span class="pre">display_name</span> <span class="pre">=</span> <span class="pre">property(lambda</span> <span class="pre">x:</span> <span class="pre">x.real_name</span> <span class="pre">or</span> <span class="pre">x.username)</span></tt></li>
</ul>
</dd>
</dl>
</div>
</div>
<div class="section" id="documentation">
<span id="styleguide-docs"></span><h1>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h1>
<p>We use <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a> to generate our API and user documentation. Read the
<a class="reference external" href="http://sphinx.pocoo.org/rest.html">reStructuredText primer</a> and <a class="reference external" href="http://sphinx.pocoo.org/contents.html">Sphinx documentation</a> as needed.</p>
<div class="section" id="special-roles">
<h2>Special roles<a class="headerlink" href="#special-roles" title="Permalink to this headline">¶</a></h2>
<p>We introduce a number of special roles for documentation:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">:bug:</span></tt> – links to a bug in Translate’s Bugzilla.<ul>
<li><tt class="docutils literal"><span class="pre">:bug:`123`</span></tt> gives: <a class="reference external" href="http://bugs.locamotion.org/show_bug.cgi?id=123">bug 123</a></li>
<li><tt class="docutils literal"><span class="pre">:bug:`broken</span> <span class="pre"><123>`</span></tt> gives: <a class="reference external" href="http://bugs.locamotion.org/show_bug.cgi?id=123">broken</a></li>
</ul>
</li>
<li><tt class="docutils literal"><span class="pre">:opt:</span></tt> – mark command options and command values.<ul>
<li><tt class="docutils literal"><span class="pre">:opt:`-P`</span></tt> gives <tt class="docutils literal"><span class="pre">-P</span></tt></li>
<li><tt class="docutils literal"><span class="pre">:opt:`--progress=dots`</span></tt> gives <tt class="docutils literal"><span class="pre">--proress=dots</span></tt></li>
<li><tt class="docutils literal"><span class="pre">:opt:`dots`</span></tt> gives <tt class="docutils literal"><span class="pre">dots</span></tt></li>
</ul>
</li>
<li><tt class="docutils literal"><span class="pre">:man:</span></tt> – link to a Linux man page.<ul>
<li><tt class="docutils literal"><span class="pre">:man:`msgfmt`</span></tt> gives :man:msgfmt</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="docstrings">
<h2>Docstrings<a class="headerlink" href="#docstrings" title="Permalink to this headline">¶</a></h2>
<dl class="docutils">
<dt>Docstring conventions:</dt>
<dd><p class="first">All docstrings are formatted with reStructuredText as understood by
Sphinx. Depending on the number of lines in the docstring, they are
laid out differently. If it’s just one line, the closing triple
quote is on the same line as the opening, otherwise the text is on
the same line as the opening quote and the triple quote that closes
the string on its own line:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">foo</span><span class="p">():</span>
<span class="sd">"""This is a simple docstring."""</span>
<span class="k">def</span> <span class="nf">bar</span><span class="p">():</span>
<span class="sd">"""This is a longer docstring with so much information in there</span>
<span class="sd"> that it spans three lines. In this case the closing triple quote</span>
<span class="sd"> is on its own line.</span>
<span class="sd"> """</span>
</pre></div>
</div>
</dd>
</dl>
<p>Please read <span class="target" id="index-3"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0257"><strong>PEP 257</strong></a> (Docstring Conventions) for a general overview,
the important parts though are:</p>
<ul class="simple">
<li>A docstring should have a brief one-line summary, ending with a period.</li>
<li>If there are more details there should be a blank line between the one-line
summary and the rest of the text. Use pragraphs and formating as needed.</li>
<li>Use <a class="reference external" href="http://sphinx.pocoo.org/domains.html#info-field-lists">reST field lists</a> to describe the input parameters and/or return types
as the last part of the docstring.</li>
<li>Use proper capitalisation and punctuation.</li>
<li>Don’t restate things that would appear in parameter descriptions.</li>
</ul>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="n">bar</span><span class="p">):</span>
<span class="sd">"""One line description.</span>
<span class="sd"> Further explanations that might be needed.</span>
<span class="sd"> :param bar: Parameter descriptions.</span>
<span class="sd"> """</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">addunit</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">unit</span><span class="p">):</span>
<span class="sd">"""Appends the given unit to the object's list of units.</span>
<span class="sd"> This method should always be used rather than trying to modify the</span>
<span class="sd"> list manually.</span>
<span class="sd"> :type unit: TranslationUnit</span>
<span class="sd"> :param unit: Any object that inherits from :class:`TranslationUnit`.</span>
<span class="sd"> """</span>
<span class="bp">self</span><span class="o">.</span><span class="n">units</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">unit</span><span class="p">)</span>
</pre></div>
</div>
<dl class="docutils">
<dt>Parameter documentation:</dt>
<dd><p class="first">Document parameters using <a class="reference external" href="http://sphinx.pocoo.org/domains.html#info-field-lists">reST field lists</a> as follows:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="n">bar</span><span class="p">):</span>
<span class="sd">"""Simple docstring</span>
<span class="sd"> :param bar: Something</span>
<span class="sd"> :type bar: Some type</span>
<span class="sd"> :return: Returns something</span>
<span class="sd"> :rtype: Return type</span>
<span class="sd"> """</span>
</pre></div>
</div>
</dd>
<dt>Cross refencing code:</dt>
<dd>When talking about other objects, methods, functions and variables
it is good practice to cross-reference them with Sphinx’s <a class="reference external" href="http://sphinx.pocoo.org/domains.html#cross-referencing-python-objects">Python
cross-referencing</a>.</dd>
<dt>Other directives:</dt>
<dd>Use <a class="reference external" href="http://sphinx.pocoo.org/markup/para.html#paragraph-level-markup">paragraph-level markup</a> when needed.</dd>
</dl>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">We still Need to gather the useful ones that we want you to use and how to use
then. E.g. how to talk about a paramter in the docstring. How to reference
classes in the module. How to reference other modules, etc.</p>
</div>
<dl class="docutils">
<dt>Module header:</dt>
<dd><p class="first">The module header consists of an utf-8 encoding declaration, copyright
attribution, license block and a standard docstring:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="c"># -*- coding: utf-8 -*-</span>
<span class="c">#</span>
<span class="o">...</span> <span class="n">LICENSE</span> <span class="n">BLOCK</span><span class="o">...</span>
<span class="sd">"""A brief description"""</span>
</pre></div>
</div>
</dd>
</dl>
</div>
<div class="section" id="comments">
<h2>Comments<a class="headerlink" href="#comments" title="Permalink to this headline">¶</a></h2>
<dl class="docutils">
<dt>General:</dt>
<dd><ul class="first simple">
<li>The <tt class="docutils literal"><span class="pre">#</span></tt> symbol (pound or hash) is used to start comments.</li>
<li>A space must follow the <tt class="docutils literal"><span class="pre">#</span></tt> between any written text.</li>
<li>Line length must be observed.</li>
<li>Inline comments are preceeded by two spaces.</li>
<li>Write sentences correctly: proper capitalisation and punctuation.</li>
</ul>
<p>Good:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># Good comment with space before and full sentence.</span>
<span class="n">statement</span> <span class="c"># Good comment with two spaces</span>
</pre></div>
</div>
<p>Bad:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="c">#Bad comment no space before</span>
<span class="n">statement</span> <span class="c"># Bad comment, needs two spaces</span>
</pre></div>
</div>
</dd>
<dt>Docstring comments:</dt>
<dd><p class="first">Rules for comments are similar to docstrings. Both are formatted with
reStructuredText. If a comment is used to document an attribute, put a
colon after the opening pound sign (<tt class="docutils literal"><span class="pre">#</span></tt>):</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">User</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="c">#: the name of the user as unicode string</span>
<span class="n">name</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">String</span><span class="p">)</span>
<span class="c">#: the sha1 hash of the password + inline salt</span>
<span class="n">pw_hash</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">String</span><span class="p">)</span>
</pre></div>
</div>
</dd>
</dl>
</div>
</div>
</div>
<hr>
<footer class="footer">
<div class="container">
<p class="pull-right"><a href="#">Back to top ↑</a></p>
<ul class="unstyled muted">
<li><small>
© 2012, Translate.org.za.<br/>
</small></li>
<li><small>
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</small></li>
</ul>
</div>
</footer>
</body>
</html>
