I’d generally prefer comments in code. The README’s are relatively sparse and contain information that would be a bit too high-level for module or class-level comments. If commentary is specific to a module or class or method, the documentation belongs there. My rule of thumb is if the commentary helps you navigate and understand rules that apply to entire sets of modules rooted at `foo/`, it generally belongs in `foo/README`.
For example “this module contains logic defining routes for serving an HTTP API. We don’t write any logic that interacts directly with db models in these modules. Rather, these modules make calls to services in `/services`, which make such calls.”
It wouldn’t make sense to duplicate this comment across every router sub-module. And it’s not obvious from looking at any one module that this rule is applied across all modules, without such guidance.
These little bits of scaffolding really help narrow down the scope of the code that LLMs eventually try to write.
I’d generally prefer comments in code. The README’s are relatively sparse and contain information that would be a bit too high-level for module or class-level comments. If commentary is specific to a module or class or method, the documentation belongs there. My rule of thumb is if the commentary helps you navigate and understand rules that apply to entire sets of modules rooted at `foo/`, it generally belongs in `foo/README`.
For example “this module contains logic defining routes for serving an HTTP API. We don’t write any logic that interacts directly with db models in these modules. Rather, these modules make calls to services in `/services`, which make such calls.”
It wouldn’t make sense to duplicate this comment across every router sub-module. And it’s not obvious from looking at any one module that this rule is applied across all modules, without such guidance.
These little bits of scaffolding really help narrow down the scope of the code that LLMs eventually try to write.
Comments are not easy for the LLM to refer to, ironically: https://taoofmac.com/space/blog/2025/05/13/2230