3 ms·
> Explaining previous approaches that didn’t work; explaining trade offs in the current implementation; marking possible improvements (TODOs) in the code; anyth
by derefr 10y ago
> Explaining previous approaches that didn’t work; explaining trade offs in the current implementation; marking possible improvements (TODOs) in the code; anything else you’d like to communicate with someone reading or developing the code
To me, those are the functions of commit messages, not code comments.
Of course, a "proper" IDE (and I don't know of any) would give you the context of the commit messages "impinging upon" any given line/block. Maybe something like Light Table (whatever happened to that?) could be configured to do this.
> Presenting an example usage of the function and example output
And that's what (formalized) docs are for. You can certainly generate those from docstring-style comments, if you like, but personally I feel like they get it the way of editing the code itself, and would be better kept in separate files.
(Consider: would you put the gettext translation table for a string, inline inside the source file that contains said string? The arguments are the same, I think.)
- fooey 10y agoif you're looking at commit messages to figure out a piece of code, you're probably having a very bad day
- yxhuvud 10y agoEh, that depends totally on the development culture. I do it all the time. Getting the history over time for a specific region is extremely nice when a piece of code is to be understood. For the emacs users: vc-region-history is the best part of emacs 25. I totally consider it nice enough to motivate people to compile 25 by yourself if your distro doesn't provide it yet.
- derefr 10y agoI feel like the most consideration that is ever spent reading a particular line of code, happens during the code review for the PR that introduces that code. When you're doing a code review, you read new code at the same time that you read the commit messages. The commit messages should explain+justify the code they commit. Heck, half the reason you can break commits down into little semantic pieces with tools like `git add -p` is so you can explain/justify each piece separately. Really, rather than what I said above, it might be better if ever line of code were just always put in context of the PR+code review that allowed it to enter the codebase. Instead of git-blame(1), github-blame(1).
- DrScump 10y agoThere's a difference between figuring out the how and fully understanding the why. Comments are for the latter.
- emodendroket 10y ago> To me, those are the functions of commit messages, not code comments. Yeah, it's definitely much more helpful to have it buried below hundreds of merge commit messages.