The idea of separating documentation from code can be viewed as an artificial distinction. Historically, we wrote documentation outside the code because the programming languages were relatively opaque and biased toward efficient compilation rather than clear exposition. Different techniques have been tried to reduce the distance between the working code and documentation pertaining to the code. Embedding more sophisticated comments, for example, is a long-standing tradition for reducing the distance between code and notes. Python takes this a step further by including a formal docstring in packages, modules, classes, and functions.
The literate programming approach to software development was pioneered by Donald Knuth. The idea is that a single source document can produce efficient code, as well as good-looking documentation. For machine-oriented assembler...
