Skip to content

Latest commit

 

History

History

3_documenting_and_testing

README.md

Documenting and Testing

In the Documenting and Testing workshop we will explore techniques to help understand code written by others, and to help write code that others can easily read, understand and trust.

Learning Objectives

Priorities: 🥚🐣🐥🐔 (click for more info)

Learning objective for this workshop are labeled so you can prioritize your study time. The emojis show the minimum mastery you are expected to achieve for each skill, but there is no maximum! If you have the time you should aim to master all of the skills introduced in this workshop.

  • 🥚 You are expected to master these skills. They are the foundations you will need to move forward.
  • 🐣 You are expected to be comfortable with these skills. It's ok if you still need help sometimes.
  • 🐥 You are expected to be familiar with these skills. It's enough to recognize them in practice and apply them with help.
  • 🐔 You are not expected to know these skills, but they are important if you want to excel. You should only focus on these after mastering the 🥚, 🐣 and 🐥 objectives.

Function Documentation

  • 🥚 You can read docstrings to understand a function's behavior.
  • 🥚 You can print a file's docstring to the console using:
    • $ python -m pydoc path/to/file.py
    • then type q to quit
  • 🥚 You can distinguish between a function's behavior, strategy and implementation.
  • 🥚 You can write a clear and complete docstring to describe a function's behavior.
  • 🥚 You can write 2-3 doctests to informally demonstrate a function's behavior. (white space matters in a docstring test case!)
  • 🥚 You can run a file's doctests from the console:
    • $ python -m doctest -v path/to/file.py

Function Implementation

  • 🥚 You can use a formatter and linter to write code that follows community conventions.
  • 🥚 You can read and write type annotations to describe a function's type signature.
  • 🥚 You can write a clear and helpful name for a function, and use the same name for the file.
  • 🥚 You can write assertions in a function for defensive programming.
  • 🐣 You can write self-documenting code that uses variable names and comments to explain a function's strategy.
  • 🐥 You can use the Zen of Python as a guide when writing your own code.

Function Testing

  • 🥚 You can read and run unit tests to understand a function's behavior.
  • 🥚 You can step through test cases in a debugger to understand a function's strategy & implementation.
    • open the function and tests side-by-side
    • place a breakpoint on the first line of the function
    • open the VSCode debugger pane
    • launch the ET: Debug Python (unittest) process
  • 🥚 You can write a suite of unit tests with some boundary cases.
  • 🐣 You can write a full suite of unit tests including comprehensive boundary cases and assertions checks.