The unsung hero of Python Programming - Documentation by Brett Drury

The unsung hero of Python Programming - Documentation

Transcript

1. The unsung hero of Python Programming - Documentation OR: How I Learned to Stop Worrying and Love Documentation Brett Drury Skim Technologies
2. whisper.sh Majority of a Programmer’s Time is Working With 1. 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
3. Why I am interested in documentation? Worked for a number 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
4. projects.raspberrypi.org Pydoc - Python’s Documentation Tool 1. Works with Doc 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
6. Commenting V Documentation “Code tells you how; Comments tell you 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
7. Doc Strings The doc string line should begin with a 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
8. Package and Module Docstrings Package docstrings should be placed at 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.
9. Related Packages pygments: Is a generic syntax highlighter suitable for 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
10. Testing as Documentation (DocTest) 1. Unit Tests expressed as doc-strings 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.
11. Recovering UML from Python Code Although we should write UML diagrams before we write code. It is possible to obtain UML diagrams on a post-hoc basis. PyReverse -> Now part of Pylint
12. Good documentation in Python Does not have to take huge 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
13. Contact: brett.drury@gmail.com I also have research interests and still publish: Causal inference from text Bayesian Reasoning for Natural Language Event prediction from text Get in contact if you want to undertake some academic research and publish it.