docstring

Docstring is a string literal used to document a module, class, function, or method in source code. In Python, a docstring is the first statement in the object's body and is accessible via __doc__, help(), and documentation tools. The term contrasts with ordinary comments, which are not part of runtime metadata.

The main purpose is to describe what the object does, how to use it, its parameters and return value, and any exceptions or side effects. Docstrings enable tool-assisted documentation generation and assist developers and users in understanding code without consulting external docs.

Conventions vary by language. Python's PEP 257 prescribes a concise summary line, followed by a longer description and optional sections such as Parameters, Returns, Raises, and Examples. The text is often written in reStructuredText or Markdown. Java uses JavaDoc with tags like @param and @return, while JavaScript often uses JSDoc with similar tags. Doxygen supports multiple languages with its own comment styles.

Best practices include keeping docstrings current, avoiding duplication with code, and writing precise, actionable descriptions. A well-maintained docstring improves readability, supports automated documentation, and aids maintenance.

Example (Python):

def add(a, b):

"""Return the sum of a and b."""

return a + b