3 ms·
i'm ambivalent about where the right place is to answer the 3 questions posted by the OP. on the one hand, it seems efficient to put meta-data in the commit ra
by diN0bot 17y ago
i'm ambivalent about where the right place is to answer the 3 questions posted by the OP.
on the one hand, it seems efficient to put meta-data in the commit rather than clouding the code itself. on the other hand, i'm much more likely to go back to a piece of code and reread my comments and architectural diagrams then visit the repo logs. if documentation is too big or orthogonal to go in a class or function comment, then i put it in the docs folder.
- gregwebs 17y agoPlacing info in the code or docs seems useful for a feature, but a bugfix may not require any code documentation, particularly if there is a test case for it.
- diN0bot 17y agoi 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.
- jparise 17y agoCommit descriptions describe the change, which is very often different than the design of the code itself. My approach is to use detailed descriptions in both places: commit logs track the evolution of the source tree, and comments/documentation describe the design and implementation of the source tree at a snapshot in time (e.g. now/tip).
- diN0bot 17y agogood point. i guess i'm overvaluing the now/tip docs. i definitely delete old docs since that just confuses everything. when i reach that point where i start wanting to revert the repo or backtrack on changes then commit docs will make much more sense. i still leave a good commit message when i can but....documenting the now/tip in the code is far more useful to me currently.