the shorter it is, the less likely it will be invalidated by some future change. This is the main rule of thumb for ARCHITECTURE — only specify things that are unlikely to frequently change. Don’t try to keep it synchronized with code.

Interfaces are less likely [and harder!] to change. (On the criteria to be used in decomposing systems into modules, Parnas).

I agree it is the difficulty in grokking a codebase. "Pattern" naming sort of helps, but I end up having to read a far bit.

On github, I always keep thinking the commit messages for each file are descriptions. Would that be more useful?