Check your understanding of the previous reading: comments, docstrings, and how to read and write function documentation.

Question 1

Enter the symbol (not its name) used for single-line comments in Python.

Show worked solution

A single-line comment starts with a # character. Everything after it, to the end of that line, is ignored by Python.

Question 2

True or False: Multi-line comments in Python are actually just triple-quoted strings.

Select one answer, then check.

True
Correct. A triple-quoted string that isn't assigned to anything or used as a docstring is simply evaluated and discarded, which is exactly why it works as a multi-line comment.
False
Not quite. Python doesn't have a dedicated multi-line comment syntax; a multi-line comment is written as a triple-quoted string.

Question 3

True or False: Single-line comments are ignored by Python, and so are only for human benefit.

Select one answer, then check.

True
Correct. Python skips over everything after a # on a line; comments exist purely to help human readers, not the interpreter.
False
Not quite. Python really does skip over comments entirely when it runs your code; they only matter to the people reading the source.

Question 4

True or False: You should always document every line of a program.

Select one answer, then check.

True
Not quite. Documentation is a spectrum of opinion, not an every-line requirement. The most common advice is to document at least every function, which is a much lower bar than every line.
False
Correct. How much to document is a judgement call that differs between programmers; there's no single rule for every line. Many people agree that, at a minimum, you should document all your functions, but that's a much lower bar than documenting every line.

Question 5

def make_time(hour:int, minute:int, second:float)->str:
    '''
    Creates a string representation of the given hour, minute, and second.
    Note that this takes into account Daylight Savings Time.

    Args:
        hour (int): The number of hours past midnight (military time).
        minute (int): The number of minutes past the hour.
        second (float): The number of seconds past the minute, which can be a
                        decimal number (indicating milliseconds).
    Returns:
        str: A string representation of the time ("hh:mm:ss.sss") including
             milliseconds.
    '''

Interpret the documentation above to fill in the blanks.

1. This function takes parameters.

2. The second parameter is named .

3. The third parameter's type is .

4. The function's return type is .

5. We want to change the type of hour to be text. You need to replace int with .

6. We want to add a new parameter named is_dst, a boolean flag for whether it is Daylight Savings Time. What is the name and type that would go in the Args section of the documentation? Don't include indentation, the colon, or a description. Just give the name and type in parentheses: .

Word bank — not all words are used

Question 6

Which of the following are reasons for commenting code?

Select every one that applies, then check.

To support code sharing
Correct. Comments help other people, or a team you're sharing code with, understand and work with that code.
To make it easier to understand our own code, later.
Correct. Comments help you pick a piece of code back up after time away, once the reasoning behind it is no longer fresh in your mind.
To test if a function has the right inputs for some given outputs
Not quite. That describes testing, done with something like assert_equal, not documentation.
To keep a copy of code that you want to eliminate, in case you need it later.
Not quite. That describes commenting out code to temporarily disable it, a different use of # than documenting what the code does.