Other People's’ Code 2. Historical Code 3. Third Party Libraries We tend to forget over-time why we have done things. 1. Not using best practises (technical debt) 2. Not Documenting Code Wastes Time. Worse Still When Developers Quit They Will Take Knowledge With Them
of companies where there was: 1. A complicated codebase 2. Minimal Documentation 3. Lack of developer motivation to document 4. Ethos of “good code documents itself” 1st Task of New Position: Document codebase to prepare for growth
Strings Generates documentation as HTML. Shows dependencies between Classes / Modules 1. Static Web Pages 2. Web-Server which connects all classes 3. Including 3rd party libraries if it has doc- strings
why.” Jeff Atwood In general, commenting is describing your code to/for developers. The intended main audience is the maintainers and developers of the Python code. realpython.com Documenting code is describing its use and functionality to your users. realpython.com wikipedia
capital letter and end with a period. The first line should be a short description. Don't write the name of the object. If there are more lines in the documentation string, the second line should be blank, visually separating the summary from the rest of the description. The following lines should be one or more paragraphs describing the object’s calling conventions, its side effects, etc. pythonforbeginners.com
the top of the package’s __init__.py file. This docstring should list the modules and sub-packages that are exported by the package. Module docstrings are placed at the top of the file even before any imports. realpython.com Sphynx has arguably replaced pydoc. It is a better renderer, with an option to render to Latex which then can be transformed into pdf.
use in code hosting, forums, wikis or other applications that need to prettify source code pydocstyle: is a static analysis tool for checking compliance with Python docstring conventions. Readthedocs: A way of hosting private and public documentation Type Hints Add hints to variables which can add information to the declared variables. For example: def testfunction(param1:int, param2:int): This will be reflected in the generated documentation
can be used as documentation. 2. Unit Tests expressed as doc-strings can be used as unit tests def my_function(a, b): """ >>> my_function(2, 3) 6 >>> my_function('a', 3) 'aaa' """ return a * b Trying: my_function(2, 3) Expecting: 6 ok Trying: my_function('a', 3) Expecting: 'aaa' ok 1 items had no tests: doctest_simple_with_docs 1 items passed all tests: 2 tests in doctest_simple_with_docs.my_function 2 tests in 2 items. 2 passed and 0 failed. Test passed.
amount of time There are good number of tools that can cut the tedium from documentation Good code does not document itself, but assists existing documentation Helps new starters quickly learn the codebase Limits knowledge exiting the business