i often leave a code comment near a bug fix if there was something non-obvious that i messed up the first time. eg, "sleep required here because blahity blah".
it is true that writing a larger overview of, say, the thread timings is useful near the thread timing tests. i'm not above just putting a thread timing explanation in the docs folder though, especially if that influences much of the architecture and coding conventions elsewhere.
commit messages seem nice to look back on, but anything that impacts the current code state should be present in the current docs. otherwise new developers and maintainers have to look through a chronology of logs messages, which presents the same problem as blogs and hacker news compared to say wikipedia.
it is true that writing a larger overview of, say, the thread timings is useful near the thread timing tests. i'm not above just putting a thread timing explanation in the docs folder though, especially if that influences much of the architecture and coding conventions elsewhere.
commit messages seem nice to look back on, but anything that impacts the current code state should be present in the current docs. otherwise new developers and maintainers have to look through a chronology of logs messages, which presents the same problem as blogs and hacker news compared to say wikipedia.