mirror of
https://github.com/kennethreitz/python-guide.git
synced 2026-06-05 14:50:19 +00:00
Tomas Thor Jonsson
99 lines
2.7 KiB
ReStructuredText
99 lines
2.7 KiB
ReStructuredText
Documenting Your Code
|
|
=====================
|
|
|
|
Documenting your code is extremely important. It is debatably even
|
|
more important than testing.
|
|
|
|
|
|
The Basics
|
|
::::::::::
|
|
|
|
|
|
Code Comments
|
|
-------------
|
|
|
|
Information regarding code comments is taken from PEP 008 (http://www.python.org/dev/peps/pep-0008/).
|
|
Block comment styling should be used when commenting out multiple lines of code.: ::
|
|
|
|
Block comments generally apply to some (or all) code that follows them,
|
|
and are indented to the same level as that code. Each line of a block
|
|
comment starts with a # and a single space (unless it is indented text
|
|
inside the comment).
|
|
Paragraphs inside a block comment are separated by a line containing a
|
|
single #.
|
|
|
|
Inline comments are used for individual lines and should be used sparingly.: ::
|
|
|
|
An inline comment is a comment on the same line as a statement. Inline
|
|
comments should be separated by at least two spaces from the statement.
|
|
They should start with a # and a single space.
|
|
Inline comments are unnecessary and in fact distracting if they state
|
|
the obvious. Don't do this:
|
|
x = x + 1 # Increment x
|
|
But sometimes, this is useful: ::
|
|
x = x + 1 # Compensate for border
|
|
|
|
Docstrings
|
|
-----------
|
|
|
|
PEP 257 is the primary reference for docstrings. (http://www.python.org/dev/peps/pep-0257/)
|
|
|
|
There are two types of docstrings, one-line and multi-line. Their names
|
|
should be fairly self explanatory.
|
|
One-line docstrings: ::
|
|
|
|
def kos_root():
|
|
"""Return the pathname of the KOS root directory."""
|
|
global _kos_root
|
|
if _kos_root: return _kos_root
|
|
...
|
|
|
|
Multi-line docstrings: ::
|
|
|
|
def complex(real=0.0, imag=0.0):
|
|
"""Form a complex number.
|
|
|
|
Keyword arguments:
|
|
real -- the real part (default 0.0)
|
|
imag -- the imaginary part (default 0.0)
|
|
|
|
"""
|
|
if imag == 0.0 and real == 0.0: return complex_zero
|
|
...
|
|
|
|
Sphinx
|
|
------
|
|
|
|
Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref`
|
|
markup language into a range of output formats including HTML, LaTeX (for
|
|
printable PDF versions), manual pages and plain text.
|
|
|
|
.. note:: This Guide is built with Sphinx_
|
|
|
|
.. _Sphinx: http://sphinx.pocoo.org
|
|
|
|
.. _restructuredtext-ref:
|
|
|
|
|
|
reStructuredText
|
|
----------------
|
|
|
|
Most Python documentation is written with reStructuredText_. The
|
|
`reStructuredText Primer <http://sphinx.pocoo.org/rest.html>`_ and the
|
|
`reStructuredText Quick Reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
|
|
should help you familiarize yourself with its syntax.
|
|
|
|
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
|
|
|
Other Tools
|
|
:::::::::::
|
|
|
|
that old thing
|
|
--------------
|
|
|
|
pycco / docco / shocco
|
|
----------------------
|
|
|
|
Ronn
|
|
----
|