I think in part he's documenting modules. Because modules often crosscut the primary hierarchy of files/classes/methods, it's awkward to document in the source itself, and so usually isn't documented at all.
Git allows documentation across files; and because commits are naturally associated with specific revisions, it can't get out of date.
{ Still, it does seem a lot of work, and it would be nice to document within the source itself; and in a way that helps and is needed by the code (so it can't get out of date). A bad example: specifically requiring/importing another class before being able to use it. This documents dependencies, and remains current or your code stops working (it would need to be an error to require a class without using it). It is a "bad example" because it doesn't help you, just raises a barrier then "helps" you cross it, like a stand-over man in an extortion racket.
What's needed is some immediate benefit (e.g. reduce code) to associating files/classes/methods in a crosscutting "module". }
Git allows documentation across files; and because commits are naturally associated with specific revisions, it can't get out of date.
{ Still, it does seem a lot of work, and it would be nice to document within the source itself; and in a way that helps and is needed by the code (so it can't get out of date). A bad example: specifically requiring/importing another class before being able to use it. This documents dependencies, and remains current or your code stops working (it would need to be an error to require a class without using it). It is a "bad example" because it doesn't help you, just raises a barrier then "helps" you cross it, like a stand-over man in an extortion racket.
What's needed is some immediate benefit (e.g. reduce code) to associating files/classes/methods in a crosscutting "module". }