A docstring is a string placed immediately after a Python function header to describe the function’s behavior. It names what parameters mean and what the function returns, helping both people and Copilot produce the intended function body. section 3.1.1 section 3.8
Write a useful docstring by making the function’s task explicit:
- Describe each parameter, including its role or expected kind of value. section 7.7.1
- State whether the function returns a value, and identify that result. section 7.7.1
- Keep the task small and well defined; a description longer than a few sentences may signal that the function should be split. section 3.6.1
- Add example calls and expected results when the docstring will also support testing. section 6.6.3
Prompting Copilot with a docstring
def larger(num1, num2): """ num1 and num2 are two numbers. Return the larger of the two numbers. """ if num1 > num2: return num1 else: return num2 The programmer chooses the function name and parameters, writes the docstring, and lets Copilot generate the body. A clear header and description reduce ambiguity compared with relying on comments alone. section 3.1.1
Executable examples
A docstring can contain doctest examples such as >>> tot_pass_yds_player('test_file.csv', 'Aaron Rodgers') followed by 800. Running the function with these cases provides evidence that its behavior matches the specification. section 6.6.3
