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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

5. View Slide

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
   

   View Slide

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
   

   View Slide

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.
   

   View Slide

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
   

   View Slide

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.
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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.
    

    View Slide