Docstring

Programs consist of instructions that a computer executes step by step. These instructions are often hard for humans to read. That is why programmers write explanatory texts alongside them. A docstring is one such explanatory text, but at a fixed location: directly at the beginning of a self-contained building block of the program. One such building block is, for example, a function, i.e. a named section that performs a specific task. The docstring states in a few sentences what this section does, what inputs it needs, and what it returns.

Why code without description becomes expensive

Software is rarely written by a single person and then never touched again. Large projects run for years, and people change. Anyone who looks at unfamiliar code six months later often no longer understands why something was solved that way. A good docstring answers this question in ten seconds. Without it, one has to trace the instructions line by line.

There is also a practical advantage. A user manual can be generated automatically from docstrings. Tools read out all the descriptive texts of a project and build a searchable website from them. The documentation of large program libraries is created in exactly this way. So the text is written only once but used in two places.

It is important to distinguish this from a comment. A comment is any arbitrary note anywhere in the code that the computer completely ignores. A docstring, on the other hand, is stored along with the program and can be retrieved at runtime. One can therefore ask a running program what a particular building block does and receive the docstring as the answer.

Structure and typical conventions

The docstring is best known from the programming language Python. There, it is written as text between three quotation marks, directly beneath the first line of a function. The language recognizes this position and automatically stores the text along with it. Other languages have similar forms, such as Javadoc in Java or specially marked comment blocks in JavaScript.

The content usually follows a fixed pattern. The first line summarizes the purpose in a single sentence. This is followed by the input values, i.e. the information the building block receives from outside. Then comes what it delivers as a result. Often it also lists the cases in which an error occurs. Example: “Calculates the value-added tax for a net amount. Expects the amount as a number. Returns the tax amount as a number.”

A typical mistake is to repeat in the docstring what is already obvious. A text like “This function adds a and b” above a function named “add” is of no use to anyone. What is useful is information that cannot be seen from the code itself: units, permissible value ranges, special cases. Equally dangerous are outdated docstrings. If the code is changed but the description is not, it actively misleads.

Docstrings as fodder for AI assistants

In the news today, the term appears mainly in connection with programming assistants. Systems like GitHub Copilot suggest the next section of code as you type. Such assistants were trained on enormous amounts of publicly available code, docstrings included. As a result, they have learned which description matches which implementation.

This works in both directions. If one writes a docstring first, the model can generate a matching code suggestion from it. Conversely, a description can be generated for existing code. Both save time, but neither replaces review by a human. A fabricated docstring often sounds convincing even though it incorrectly represents the actual behavior.

The principle also plays a role outside of programming. If an AI system is meant to use external tools, such as a weather lookup, it needs a description of that tool. This description is often exactly the docstring of the corresponding function. How precisely it is worded therefore also determines whether the AI system chooses the right tool.