<!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>2. Style guide — Python v3.2.2 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '3.2.2',
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/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python v3.2.2 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Python v3.2.2 documentation" href="../index.html" />
<link rel="up" title="Documenting Python" href="index.html" />
<link rel="next" title="3. reStructuredText Primer" href="rest.html" />
<link rel="prev" title="1. Introduction" href="intro.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="rest.html" title="3. reStructuredText Primer"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="intro.html" title="1. Introduction"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python v3.2.2 documentation</a> »</li>
<li><a href="index.html" accesskey="U">Documenting Python</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="style-guide">
<h1>2. Style guide<a class="headerlink" href="#style-guide" title="Permalink to this headline">¶</a></h1>
<p>The Python documentation should follow the <a class="reference external" href="http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2009.pdf">Apple Publications Style Guide</a>
wherever possible. This particular style guide was selected mostly because it
seems reasonable and is easy to get online.</p>
<p>Topics which are either not covered in Apple’s style guide or treated
differently in Python documentation will be discussed in this
document.</p>
<div class="section" id="use-of-whitespace">
<h2>2.1. Use of whitespace<a class="headerlink" href="#use-of-whitespace" title="Permalink to this headline">¶</a></h2>
<p>All reST files use an indentation of 3 spaces. The maximum line length is 80
characters for normal text, but tables, deeply indented code samples and long
links may extend beyond that.</p>
<p>Make generous use of blank lines where applicable; they help grouping things
together.</p>
<p>A sentence-ending period may be followed by one or two spaces; while reST
ignores the second space, it is customarily put in by some users, for example
to aid Emacs’ auto-fill mode.</p>
</div>
<div class="section" id="footnotes">
<h2>2.2. Footnotes<a class="headerlink" href="#footnotes" title="Permalink to this headline">¶</a></h2>
<p>Footnotes are generally discouraged, though they may be used when they are the
best way to present specific information. When a footnote reference is added at
the end of the sentence, it should follow the sentence-ending punctuation. The
reST markup should appear something like this:</p>
<div class="highlight-rest"><div class="highlight"><pre>This sentence has a footnote reference. <span class="s">[#]_</span> This is the next sentence.
</pre></div>
</div>
<p>Footnotes should be gathered at the end of a file, or if the file is very long,
at the end of a section. The docutils will automatically create backlinks to
the footnote reference.</p>
<p>Footnotes may appear in the middle of sentences where appropriate.</p>
</div>
<div class="section" id="capitalization">
<h2>2.3. Capitalization<a class="headerlink" href="#capitalization" title="Permalink to this headline">¶</a></h2>
<div class="sidebar">
<p class="first sidebar-title">Sentence case</p>
<p class="last">Sentence case is a set of capitalization rules used in English
sentences: the first word is always capitalized and other words are
only capitalized if there is a specific rule requiring it.</p>
</div>
<p>Apple style guide recommends the use of title case in section titles.
However, rules for which words should be capitalized in title case
vary greaty between publications.</p>
<p>In Python documentation, use of sentence case in section titles is
preferable, but consistency within a unit is more important than
following this rule. If you add a section to the chapter where most
sections are in title case you can either convert all titles to
sentence case or use the dominant style in the new section title.</p>
<p>Sentences that start with a word for which specific rules require
starting it with a lower case letter should be avoided in titles and
elsewhere.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Sections that describe a library module often have titles in the
form of “modulename — Short description of the module.” In this
case, the description should be capitalized as a stand-alone
sentence.</p>
</div>
<p>Many special names are used in the Python documentation, including the names of
operating systems, programming languages, standards bodies, and the like. Most
of these entities are not assigned any special markup, but the preferred
spellings are given here to aid authors in maintaining the consistency of
presentation in the Python documentation.</p>
<p>Other terms and words deserve special mention as well; these conventions should
be used to ensure consistency throughout the documentation:</p>
<dl class="docutils">
<dt>CPU</dt>
<dd>For “central processing unit.” Many style guides say this should be
spelled out on the first use (and if you must use it, do so!). For
the Python documentation, this abbreviation should be avoided since
there’s no reasonable way to predict which occurrence will be the
first seen by the reader. It is better to use the word “processor”
instead.</dd>
<dt>POSIX</dt>
<dd>The name assigned to a particular group of standards. This is always
uppercase.</dd>
<dt>Python</dt>
<dd>The name of our favorite programming language is always capitalized.</dd>
<dt>reST</dt>
<dd>For “reStructuredText,” an easy to read, plaintext markup syntax
used to produce Python documentation. When spelled out, it is
always one word and both forms start with a lower case ‘r’.</dd>
<dt>Unicode</dt>
<dd>The name of a character coding system. This is always written
capitalized.</dd>
<dt>Unix</dt>
<dd>The name of the operating system developed at AT&T Bell Labs in the early
1970s.</dd>
</dl>
</div>
<div class="section" id="affirmative-tone">
<h2>2.4. Affirmative Tone<a class="headerlink" href="#affirmative-tone" title="Permalink to this headline">¶</a></h2>
<p>The documentation focuses on affirmatively stating what the language does and
how to use it effectively.</p>
<p>Except for certain security risks or segfault risks, the docs should avoid
wording along the lines of “feature x is dangerous” or “experts only”. These
kinds of value judgments belong in external blogs and wikis, not in the core
documentation.</p>
<p>Bad example (creating worry in the mind of a reader):</p>
<blockquote>
<div>Warning: failing to explicitly close a file could result in lost data or
excessive resource consumption. Never rely on reference counting to
automatically close a file.</div></blockquote>
<p>Good example (establishing confident knowledge in the effective use of the language):</p>
<blockquote>
<div>A best practice for using files is use a try/finally pair to explicitly
close a file after it is used. Alternatively, using a with-statement can
achieve the same effect. This assures that files are flushed and file
descriptor resources are released in a timely manner.</div></blockquote>
</div>
<div class="section" id="economy-of-expression">
<h2>2.5. Economy of Expression<a class="headerlink" href="#economy-of-expression" title="Permalink to this headline">¶</a></h2>
<p>More documentation is not necessarily better documentation. Err on the side
of being succinct.</p>
<p>It is an unfortunate fact that making documentation longer can be an impediment
to understanding and can result in even more ways to misread or misinterpret the
text. Long descriptions full of corner cases and caveats can create the
impression that a function is more complex or harder to use than it actually is.</p>
<p>The documentation for <a class="reference internal" href="../library/functions.html#super" title="super"><tt class="xref py py-func docutils literal"><span class="pre">super()</span></tt></a> is an example of where a good deal of
information was condensed into a few short paragraphs. Discussion of
<a class="reference internal" href="../library/functions.html#super" title="super"><tt class="xref py py-func docutils literal"><span class="pre">super()</span></tt></a> could have filled a chapter in a book, but it is often easier to
grasp a terse description than a lengthy narrative.</p>
</div>
<div class="section" id="code-examples">
<h2>2.6. Code Examples<a class="headerlink" href="#code-examples" title="Permalink to this headline">¶</a></h2>
<p>Short code examples can be a useful adjunct to understanding. Readers can often
grasp a simple example more quickly than they can digest a formal description in
prose.</p>
<p>People learn faster with concrete, motivating examples that match the context of
a typical use case. For instance, the <a class="reference internal" href="../library/stdtypes.html#str.rpartition" title="str.rpartition"><tt class="xref py py-func docutils literal"><span class="pre">str.rpartition()</span></tt></a> method is better
demonstrated with an example splitting the domain from a URL than it would be
with an example of removing the last word from a line of Monty Python dialog.</p>
<p>The ellipsis for the <a class="reference internal" href="../library/sys.html#sys.ps2" title="sys.ps2"><tt class="xref py py-attr docutils literal"><span class="pre">sys.ps2</span></tt></a> secondary interpreter prompt should only be
used sparingly, where it is necessary to clearly differentiate between input
lines and output lines. Besides contributing visual clutter, it makes it
difficult for readers to cut-and-paste examples so they can experiment with
variations.</p>
</div>
<div class="section" id="code-equivalents">
<h2>2.7. Code Equivalents<a class="headerlink" href="#code-equivalents" title="Permalink to this headline">¶</a></h2>
<p>Giving pure Python code equivalents (or approximate equivalents) can be a useful
adjunct to a prose description. A documenter should carefully weigh whether the
code equivalent adds value.</p>
<p>A good example is the code equivalent for <a class="reference internal" href="../library/functions.html#all" title="all"><tt class="xref py py-func docutils literal"><span class="pre">all()</span></tt></a>. The short 4-line code
equivalent is easily digested; it re-emphasizes the early-out behavior; and it
clarifies the handling of the corner-case where the iterable is empty. In
addition, it serves as a model for people wanting to implement a commonly
requested alternative where <a class="reference internal" href="../library/functions.html#all" title="all"><tt class="xref py py-func docutils literal"><span class="pre">all()</span></tt></a> would return the specific object
evaluating to False whenever the function terminates early.</p>
<p>A more questionable example is the code for <a class="reference internal" href="../library/itertools.html#itertools.groupby" title="itertools.groupby"><tt class="xref py py-func docutils literal"><span class="pre">itertools.groupby()</span></tt></a>. Its code
equivalent borders on being too complex to be a quick aid to understanding.
Despite its complexity, the code equivalent was kept because it serves as a
model to alternative implementations and because the operation of the “grouper”
is more easily shown in code than in English prose.</p>
<p>An example of when not to use a code equivalent is for the <a class="reference internal" href="../library/functions.html#oct" title="oct"><tt class="xref py py-func docutils literal"><span class="pre">oct()</span></tt></a> function.
The exact steps in converting a number to octal doesn’t add value for a user
trying to learn what the function does.</p>
</div>
<div class="section" id="audience">
<h2>2.8. Audience<a class="headerlink" href="#audience" title="Permalink to this headline">¶</a></h2>
<p>The tone of the tutorial (and all the docs) needs to be respectful of the
reader’s intelligence. Don’t presume that the readers are stupid. Lay out the
relevant information, show motivating use cases, provide glossary links, and do
your best to connect-the-dots, but don’t talk down to them or waste their time.</p>
<p>The tutorial is meant for newcomers, many of whom will be using the tutorial to
evaluate the language as a whole. The experience needs to be positive and not
leave the reader with worries that something bad will happen if they make a
misstep. The tutorial serves as guide for intelligent and curious readers,
saving details for the how-to guides and other sources.</p>
<p>Be careful accepting requests for documentation changes from the rare but vocal
category of reader who is looking for vindication for one of their programming
errors (“I made a mistake, therefore the docs must be wrong ...”). Typically,
the documentation wasn’t consulted until after the error was made. It is
unfortunate, but typically no documentation edit would have saved the user from
making false assumptions about the language (“I was surprised by ...”).</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">2. Style guide</a><ul>
<li><a class="reference internal" href="#use-of-whitespace">2.1. Use of whitespace</a></li>
<li><a class="reference internal" href="#footnotes">2.2. Footnotes</a></li>
<li><a class="reference internal" href="#capitalization">2.3. Capitalization</a></li>
<li><a class="reference internal" href="#affirmative-tone">2.4. Affirmative Tone</a></li>
<li><a class="reference internal" href="#economy-of-expression">2.5. Economy of Expression</a></li>
<li><a class="reference internal" href="#code-examples">2.6. Code Examples</a></li>
<li><a class="reference internal" href="#code-equivalents">2.7. Code Equivalents</a></li>
<li><a class="reference internal" href="#audience">2.8. Audience</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="intro.html"
title="previous chapter">1. Introduction</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="rest.html"
title="next chapter">3. reStructuredText Primer</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li><a href="../_sources/documenting/style.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="rest.html" title="3. reStructuredText Primer"
>next</a> |</li>
<li class="right" >
<a href="intro.html" title="1. Introduction"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python v3.2.2 documentation</a> »</li>
<li><a href="index.html" >Documenting Python</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2011, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="http://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Sep 04, 2011.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
