FrançaisGet started

Documentation

Commenting and documenting your code: the comment that adds something or merely paraphrases, a function's header (role, parameters, returned value, preconditions) and documentation that stays in step with the code.

  • 27 cards
  • 5 topics
  • Free
Study this deck

The outline, topic by topic

Each topic is weighted the way the exam weighs it.

  1. Concepts
  2. Questions
  3. Sort and link
  4. Scenarios
  5. Understand

A few cards from the deck

  • Comment: what is it?

    Show the answer

    Text in the program that is ignored when it runs, written for the readers of the code; in Python, it starts with a hash sign and ends with the line.

    It is there to say what the code does not: a reason, an assumption, a unit. i = i + 1 # adds 1 teaches nothing.

  • Which comment adds information this code does not give?

    ```python
    total = total + note * 5
    `

    • # marks out of 20 scaled to 100
    • # adds note * 5 to total
    • # multiplies the mark by 5
    • # updates the total variable
    Show the answer

    # marks out of 20 scaled to 100

    The other three comments restate the code line by line. Only the first gives the reason for the 5: a change of scale.

  • A good comment explains the … of a choice, not the …, which the code already says.

    Show the answer

    A good comment explains the why of a choice, not the what, which the code already says.

    # marks are out of 20, scaled to 100 gives information that note * 5 alone does not.

  • Docstring: what is it?

    Show the answer

    Text between triple quotes placed right under the def line, which Python keeps in memory and the built-in help can display.

    Unlike a comment, it can be read at run time: help(aire) or aire.__doc__ returns it.

  • You change a function: it now returns an integer instead of a float. What do you do with its header?

    • I fix it in the same change as the code
    • I leave it: it described the original intent
    • I will fix it at the end of the project, with all the documentation
    • I move it into a comment next to the return
    Show the answer

    I fix it in the same change as the code

    A header that no longer matches the code misleads callers. The moment the code changes is the only moment when you know precisely what changed.

Study this deck