4 ms·
I love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the comm
by simonw 5y ago
I love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the commit. That way I can use as much space as I like for it and the timestamps make it clear that it's historical commentary, not a description of how the code works right now.
- Normal_gaussian 5y agoI find an issue link only works if e is a good enough comment alongside it (ie. Attempting to eliminate this mutex is bug prone, see <link> for archiyectures and their problems).
- bentcorner 5y agoOne caveat with this method is that your source control system evolves and things get archived. Code is around forever but everything around it may change. 10 or 20 years from now your code may still be running, the issue system or the git commit log may not be.
- simonw 5y agoI am fiercely protective of my issue tracker and source history for exactly that reason. I have tools that can grab a full backup should I ever switch to something else: https://datasette.io/tools/github-to-sqlite https://datasette.io/tools/github-to-sqlite
- neolog 5y agoSome people advocate putting lots of stuff into commit messages, which makes me think I'm missing something -- commit messages are much less visible/accessible than comments in my workflow, so I don't expect my commit message to be seen. Do you always read the whole git history of a file before editing it? What interface do you use for that?
- simonw 5y agoThe GitHub web interface, specifically the "blame" view for a file.
- neolog 5y agoThat only shows the most recent commit, which is IME often not substantive, just some treewide commit like "autoformat" or "moved class into another file" or whatever. I can click on the parent commit button repeatedly until I find all the info but that's really not a good interface for exposing the history of a class.
- pmoleri 5y agoVSCode git-lens. Mandatory extension. Either way, I think both are useful, although for documenting weird code I think code comments are more important. I the commit message you should explain why you change the code. In the code, why it works like that.
- SilverRed 5y agogitlens is incredible. It passively educates on the git history so you learn about how old each section is and who was mostly behind it or worked with it last without ever requiring dedicated effort since it just sits there at the end of the selected line. I still wouldn't use git as a replacement for comments since git history is wiped out all the time. Moving files or reformatting or a million other things could remove a critical commit message.
- dragonwriter 5y ago> I love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the commit. Having worked with codebases that have switched SCMs and SCM-adjacent issue management systems multiple times without retaining full history, I'd prefer to have the commentary in code even if it is also in those other places.