Re: README.md files per directory

On 16 Apr 2026, at 19:48, Adrian Chadd <[email protected]> wrote:
> 
> On Thu, 16 Apr 2026 at 11:34, Farhan Khan <[email protected]> wrote:
>> 
>> Any thoughts on having README.md files in each directory? It would describe what the code was for, the maintainer, things that might help a would-be developer, status, TODOs, etc.
>> 
>> There's some code I recently found that I had no idea what it was until I asked AI. It might also be useful in public code displayers, such as Github, Gitea, etc.
> 
> Honestly I've wondered about potentially putting README.md files in
> places to basically be a "Design Doc" summary of the subsystem
> (notably net80211, but also describing ifnet and desired locking
> examples, how the USB stack functions, etc.)
> 
> I don't think we have any guidelines about it yet.

It’s a good first step, but a lot of directories (particularly in the kernel) have a lot of files and a *very* scarce on comments.  I would love to have a policy that each file should start with a top-level comment explaining what the file is for and what the key abstractions are.  If you don’t already see the need for this: Pick a random file in the FreeBSD repository that you’ve never looked at before and see how long it takes you to figure out what it is for and why.

David