With readability of the code being a main focus for Python developers, proper

commenting is naturally important. Some best practice apply to code comments

and project documents, depending on the scope of the project.

Project documents

A README file at the root directory give general information to the users and

the maintainers. It should be raw text or written in some very easy to read

markup, such as reStructuredText and Markdown. It should contain a few lines

explaining the purpose of the project or the library (without assuming the user

knows anything about the project), the url of the main source for the software,

and some basic credit information. This file is the main entry point for

readers of the code.

An INSTALL file is less often necessary with python, except if the dependencies

are complex or unusual, or if some C modules need to be compiled before use.

The installation instructions are often reduced to one command, such as ``pip

install module`` or ``python setup.py install`` and added to the README file.

A LICENSE file should always be present and specify the license under which the

software is made available to the public.

A TODO file or a TODO section in README should list the planned modifications

of the code.

A CHANGELOG file or section in README should compile a short overview of the

changes in the code base for the latest versions.

Documentation

As the project or library reaches a certain level of complexity, it may require

a fuller documentation, which can be of different flavors:

The introduction may show a very short overview of what can be done with the

product, using one or two extremely simplified use cases.

The tutorials will show in more details some main use cases. The reader will

follow a step-by-step procedure to set-up a working prototype.

The API reference, which is often generated automatically from the code, will

list all publicly available interfaces, their parameters and their return

values, with an explanation of their use.

Some documents intended for developers might give guidance about code

convention and general design decision of the project.

Comments

Comments are written directly inside the code, either using the hash sign (#)

or a docstring_.

Finding the correct balance between undocumented code and verbose and useless

comment boilerplates is difficult, and is the subject of heated discussion

among developers.

The following guidelines seem to be most commonly agreed upon:

**Wrong or outdated comments are worse than no comments at all.** Following the

saying that it is better, on a boat, to know that we do not know were we are

than to wrongly believe we know where we are, wrong or outdated comments can be

misleading for the maintainers, slow down considerably bug hunting or

refactoring, and then, when discovered wrong, they will throw suspicion on all

other comments in the code, regardless of their individual correctness.

**No need comments for perfect code...** An hypothetical perfectly readable

code, with a crystal clear logic stream, expressive variable and function

names, orthogonal segmentation passing exactly between the flesh and the bones,

and no implicit assumptions of any kind, would not require any comment at all.

When striving for coding excellence, it is useful to see any existing comment,

or any feeling of a need for a comment, as the sign that the code do not

express clearly enough its intent and can be improved.

**.. but no code is perfect.** Perfect code is a chimere, it exists only in

our dreams. In real life, a code base is full of trade offs, and comments are

often needed in the most difficult parts. Moreover, any special case, any

obscure hack, any monkey patch and any ugly workaround MUST be signaled and

explained by a proper comment. This should be enforced by the law!

**TODOs** are special comments that a developer write as a reminder for later

use. It is said that its original intent was that someone might, one day,

search for the string "TODO" in the code base and actually roll their sleeves

and start *to do the TODOs*. There is no avalaible record that it ever

happened. However, TODOs comment are still very useful, because they mark the

current limits of the code, and it is not unlikely that, when required to add a

new behavior to the actual code, looking at the TODOs will show where to start.

**Do not use triple-quote strings to comment code.** A common operation when

modifiying code is to comment out some lines or even a full function or class

definition. This can be done by adding triple-quotes around the code block to

be skipped, but this is not a good pratice, because line-oriented command-line

tools such as ``grep`` will not be aware that the commented code is inactive.

It is better to add hashes at the proper indentation level for every commented

line. Good editors allow to do this with few keystrokes (ctrl-v on Vim).

**Bad**

.. code-block:: python

**Good**

.. code-block:: python