CASA Python Coding Standards
General Python Coding Standards
- Python PEP 8
Python Docstring Coding Standards
- Python PEP 257
- Exception to PEP 257, proposed by Rob Reid
Section "Multi-line Docstrings", paragraph 4", reads:
The docstring for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each. (These summaries generally give less detail than the summary line in the object's docstring.) The docstring for a package (i.e., the docstring of the package's init
.py module) should also list the modules and subpackages exported by the package.
That seems like a mistake. We should be (and are) able to add things to modules and modules to packages without updating a global list of them. Such lists are prone to being out of date, and thus make unreliable documentation. IMHO it's better to
to see what's there.