A docstring is a multiline string that documents a code component’s inputs, behavior, and outputs. In Python, it appears inside a function between triple quotes and helps readers understand the function without studying every implementation detail. section 21.3 section 20.2
Documenting an attendance function
def take_attendance(classroom, who_is_here): """ classroom, tuple of strings who_is_here, tuple of strings Prints the names of students who are present Returns a string, "finished taking attendance" """ Read the docstring from top to bottom: it identifies each input and type, describes the task, and states the returned value. A reader can understand the function’s contract before examining its loop and condition. section 21.1 section 21.3
def take_attendance(classroom, who_is_here):
"""
classroom, tuple of strings
who_is_here, tuple of strings
Prints the names of all kids in class who are also in who_is_here
Returns a string, "finished taking attendance"
"""
Inspect the compact function specification for a complete example of parameter names, types, behavior, and return information. section 21.3
Use this checklist when writing a docstring:
- Name every input parameter and give its type. section 21.3
- Briefly state what the function does, including important printed effects. section 21.1 section 20.2
- Describe the return value and its type. section 21.3
- Keep the specification separate from implementation details so users can treat the function as a black box. section 22.1 section 20.2
