> It is thankfully common wisdom nowadays that documentation must be placed as near as possible to the code it documents, and should be fine-grained to a minima

> It is thankfully common wisdom nowadays that documentation must be placed as near as possible to the code it documents, and should be fine-grained to a minimal unit of describability (the thing being documented). I think that documentation which describes each part of a codebase in isolation, without explaining the project's architecture and high-level information and control flow, is a common failure mode of fine-grained "doc comment" based documentation (Doxygen, to an extent Rustdoc, possibly Javadoc but I don't write much Java). I'm looking forward to more projects adopting https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html or similar, particularly to help code contributors who don't already have a maintainer's birds-eye picture of the codebase. > The codebase becomes more modular. Individual parts can be extracted into different crates or projects if necessary, and strong abstraction boundaries make the code easier to understand in small pieces. I'd argue that a codebase with too many interacting parts, abstractions or indirections, and possibly excessive modularity, can sometimes result in a system more intimidating to learn than a more straight-line approach (http://number-none.com/blow/john_carmack_on_inlined_code.html http://number-none.com/blow/john_carmack_on_inlined_code.htm...). Otherwise I'd largely agree with this post. Another reason to not define the errors returned by a function separately from the function itself, is because of DRY and "every piece of knowledge must have a single, unambiguous, authoritative representation within a system". In this case, allowing a function to return a new error should not require adding that error in a global enum, and separately adding that error return in the actual function located far away from that enum. And finding which function an error value comes from should not require searching the whole codebase for 1 or more occurrences of that value's type.