My favourite projects typically have documentation in comments.
One example is SpiderMonkey, which uses these beautiful, long expository comments explaining not only what, but why design choices have been made. <a href="https://searchfox.org/firefox-main/source/js/public/RootingAPI.h#33" rel="nofollow">https://searchfox.org/firefox-main/source/js/public/RootingA...
If the goal is "locality", you can't get much closer than as a comment.
As far as markdown becoming "source code for agents" under the agentic paradigm, per-directory `AGENTS.md` seems more consistent, at least visually. If agent managed markdown is going to be high-churn, I'd rather it be confined to a single file. Constraints, especially for agents, are good.
In my adjunct teaching I tell all my students to focus on "why" comments. Everyone parrots that code should be self-commenting, and for the most part they are correct (conceding that, for long cryptic lines of regex, or trendy Python one-liners, the "what" comments can still be useful) -- but they miss the core idea of why comments are useful. I can't see into your brain as the other programmer. To me, your design choice might appear stupid, brainless, or completely baffling; but if you put a comment telling me why you did it that way, I'm a lot less likely to get fixated on the shenanigans when I'm the guy picking up your code 5 years later.
fifferfaffer · · focus · HN ↗
One example is SpiderMonkey, which uses these beautiful, long expository comments explaining not only what, but why design choices have been made. <a href="https://searchfox.org/firefox-main/source/js/public/RootingAPI.h#33" rel="nofollow">https://searchfox.org/firefox-main/source/js/public/RootingA...
If the goal is "locality", you can't get much closer than as a comment.
As far as markdown becoming "source code for agents" under the agentic paradigm, per-directory `AGENTS.md` seems more consistent, at least visually. If agent managed markdown is going to be high-churn, I'd rather it be confined to a single file. Constraints, especially for agents, are good.
lucicditee · · focus · HN ↗