1. Coding and Documentation Style Guide¶

This document contains a style guide for Python programming. The coding style follows the recommendations from [pep8] with some differences outlined here. The documentation style is inspiriert by the [numpydoc]. This document assumes the use of Python 3.

And, by the way…

Code are written to read by humans and only incidental interpreted by a computer.

1.1. Coding Style¶

Global Variable

1.1.1. Naming Conventions¶

Note

Never use l, O, or I single letter names as these can be mistaken for 1 and 0, depending on typeface:

Python¶

O = 2    # This may look like you're trying to reassign 2 to zero

Name	Formatting	Used for
single lowercase letter	b
single uppercase letter	B
lowercase	twowords	package, module
lower_case_with_underscores	two_words	function, varibale
UPPERCASE	TWOWORDS
UPPER_CASE_WITH_UNDERSCORES	TWO_WORDS	constants
CapitalizedWords	TwoWords	classes
mixedCase	twoWords
Capitalized_Words_With_Underscores	Two_Words

1.1.1.1. Package and Module Names¶

start with a letter
lower case
starts with a underline only for «non public» moduls in a package
a…z|0…9|_

1.1.1.2. Class Names¶

CamelCase

1.1.1.3. Exception Names¶

1.1.1.4. Global Variable Names¶

1.1.1.5. Function and Variable Names¶

lower case
start with a letter
underline to improve the readlibity
a…z|0…9|_
starts with a underline only for «non public» function in a module

1.1.1.6. Function and Method Arguments¶

Always use self for the first argument to instance methods.

Always use cls for the first argument to class methods.

1.1.1.7. Method Names and Instance Variables¶

1.1.1.8. Constants¶

upper case
underline to improve the readlibity

1.1.2. Code Layout¶

1.1.2.1. Blanke Lines¶

Surround top-level functions and classes with two blank lines.
Surround method definitions inside classes with a single blank line.
Use blank lines sparingly inside functions to show clear steps.

1.2. Documentation Style¶

A documentation string (docstring) is a string that describes a module, function, class, or method definition. The docstring is a special attribute of the object (object.__doc__) and, for consistency, is surrounded by triple double quotes, i.e.:

This document describes the syntax and best practices for docstrings used with the [napoleon] extension for [sphinx].

This section is a compilation from the documentation of the [napoleon] and [numpydoc] extetions.

1.2.1. Examples in docstrings¶

These are written in doctest format, and should illustrate how to use the function.

If posible every example should work on it’s one. The benevit is that the examples can tested with the command:

[docs]$ make doctest

1.3. References¶

pep8: PEP 8, Style Guide for Python Code; Guido van Rossum, Barry Warsaw, Nick Coghlan, https://www.python.org/dev/peps/pep-0008/
sphinx: Sphinx, Python Documentaion Generator, https://www.sphinx-doc.org/
napoleon(1,2): sphinx.ext.napoleon – Support for NumPy and Google style docstrings, https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
numpydoc(1,2): numpydoc docstring guide, https://numpydoc.readthedocs.io/

mrdevtools