Good function documentation should:

Question

BlackTom AI · Accepted Answer

Docstrings describe a function’s purpose, its parameters, return values, and usage, so the best practice is to include a clear docstring and explanatory comments that tell future readers why and how the code works (option b).

1) Relevant knowledge points and concepts
- Docstrings (e.g., Python triple-quoted strings) document the function’s interface: purpose, input types/meaning, return values, exceptions, and examples. They support readability, automated documentation tools (Sphinx, pydoc), and correct usage.
- Comments inside the function should explain the rationale, design choices, and non-obvious implementation details (“why”), not restate obvious code (“what”).
- Excessive line-by-line comments are noisy; comments should be purposeful and maintainable.

2) Step-by-step reasoning
- A good docstring immediately tells a caller how to use the function (what inputs are expected and what outputs to expect). This meets the question’s requirement to document inputs and outputs.
- Comments throughout the body that explain why a particular algorithm or step is used help maintainers understand trade-offs and edge cases.
- Combining both (docstring + targeted comments) provides both external API documentation and internal rationale, improving reuse and debugging.

3) Calculations / intermediate steps
- Not applicable here (no numeric calculation). The logical steps above lead to the selection of option b.

4) Why the correct answer is correct
- Option b explicitly combines an interface-level docstring (inputs/outputs) with explanatory comments (why/how), which is the accepted best practice in software engineering for clarity, maintainability, and tooling.

5) Why other options are incorrect
- a: “Explain what each line does” is unnecessary and often redundant; good code + concise comments are preferable. Line-by-line comments clutter and age badly.
- c: “Be as short as possible to minimise file size” sacrifices clarity for negligible space savings; documentation is about clarity.
- d: “Never be included” is false: putting a docstring in the function file is standard practice; external docs can supplement but should not replace inline docstrings.

Conclusion: therefore option b is correct, matching the provided answer.

Good function documentation should:单项选择题

类似问题

Internal documentation involves

An advantage of including internal documentation in the code of an application is

An advantage of including internal documentation in the code of an application is

Internal documentation involves

[Readme: Assignment Requirements (CODE)] Failure to document code, will result in lost points on labs and assignments. See also "Syllabus - Additional Information".

How should you reference a book in code?

How should you reference online sources in code?

Which of the following is NOT something that should be included in method-level documentation in Java?

更多留学生实用工具

智能学习助手

风格化写作助手

论文查重助手

文献引用助手

课堂转译助手

课堂笔记助手

Quiz搜索助手

学校历年真题

智能刷题助手

智能匹配练习

希望你的学习变得更简单