That depends entirely on the toolset available. Languages like Java, Python or Golang enable inline documentation which can then be used by standardized tools

That depends entirely on the toolset available. Languages like Java, Python or Golang enable inline documentation which can then be used by standardized tools (Javadoc, Docstrings, Godoc). eg. https://pkg.go.dev/flag@go1.17.6#PrintDefaults https://pkg.go.dev/flag@go1.17.6#PrintDefaults The entire documentation of this function (including HTML) is generated by the Godoc tool reading comments which conform to a certain convention. https://cs.opensource.google/go/go/+/refs/tags/go1.17.6:src/flag/flag.go;l=541 https://cs.opensource.google/go/go/+/refs/tags/go1.17.6:src/... There is literally no downside to this. The code and its documentation are in the same file, its much simpler for developers to update it when there is a change, and its easy to generate documentation directly from source on the fly.