What content should documentation strings or API contracts include?

• A. Only the function name and a single word description.
• B. Formatting preferences and font sizes.
• C. Purpose, parameters, return values, side effects, exceptions, and examples.
• D. Internal implementation details and code comments.

Answer: (C)

Documentation strings and API contracts should describe how to use a function, not how it’s implemented. They need to spell out the function’s intent and how callers should interact with it: the purpose of the function, the parameters (including their meaning and expected types), the return values (what is returned and in what form), any side effects or state changes, any exceptions or error conditions that can be raised, and practical examples showing typical and edge-case usage. This combination gives a complete external view of the function’s behavior, helping users rely on the contract without digging into the code.

Why this choice fits best: it provides all the information a caller needs to use the function correctly and predictably, and it remains useful across implementations or refactors since it describes behavior rather than internal details.

Formatting preferences, fonts, or other presentation choices aren’t part of the function’s behavior and don’t help a caller understand how to use it.

Internal implementation details and code comments reveal how the function works internally, which can mislead or confuse callers about what is guaranteed or expected by the contract.