4 ms·

One approach I've seen used is placing comments in the body of version-control commits (on Git, beyond the first line). This clearly attaches them to a specifi

One approach I've seen used is placing comments in the body of version-control commits (on Git, beyond the first line). This clearly attaches them to a specific revision of the code, which is also automatically superseded when some other change overwrites that line. It's not far off to have a code editor plugin that shows this information visually beside the file. Kind of like the visual "git blame" in IntelliJ IDEs, but for the commit message.

WalterGR 5y ago
Wait, so to read code comments you have to use ‘blame’ and for a line of code sort through the commits to find any potentially relevant comments? And then do it for the next line, and the next... I must be misunderstanding.
- kroltan 5y ago
  Yes, that's correct. With a sane commit history it works quite reasonably. It's a bit of a hassle but any out-of-band information is by definition a nonzero hassle to find unless a tool does it for you. Also, "potentially relevant commits" are just all commits that change that line or lines. Following this principle, there is no justification to make a change where you can't document why it is so.
  - WalterGR 5y ago
    Following this principle, there is no justification to make a change where you can't document why it is so. So the comments in the commit messages are an explanation / justification of changes, and they don’t replace code comments? That just seems like “how you’re supposed to do it” and wouldn’t address code comments not being revised when necessary.
- avisser 5y ago
  The better version is to have something like gitlens installed into your IDE and have it dynamically render those git comments. https://github.com/Axosoft/vscode-gitlens#current-line-blame- https://github.com/Axosoft/vscode-gitlens#current-line-blame...
  - WalterGR 5y ago
    That looks like an awesome tool. Thanks for the link.
interactivecode 5y ago
Next thing you know someone both edits and renames a file and you lose all your extensive documentation
- kroltan 5y ago
  Well, at least they will document why they edited-and-renamed the file!

WalterGR 5y ago

Wait, so to read code comments you have to use ‘blame’ and for a line of code sort through the commits to find any potentially relevant comments? And then do it for the next line, and the next... I must be misunderstanding.

kroltan 5y ago
Yes, that's correct. With a sane commit history it works quite reasonably. It's a bit of a hassle but any out-of-band information is by definition a nonzero hassle to find unless a tool does it for you. Also, "potentially relevant commits" are just all commits that change that line or lines. Following this principle, there is no justification to make a change where you can't document why it is so.
- WalterGR 5y ago
  Following this principle, there is no justification to make a change where you can't document why it is so. So the comments in the commit messages are an explanation / justification of changes, and they don’t replace code comments? That just seems like “how you’re supposed to do it” and wouldn’t address code comments not being revised when necessary.
avisser 5y ago
The better version is to have something like gitlens installed into your IDE and have it dynamically render those git comments. https://github.com/Axosoft/vscode-gitlens#current-line-blame- https://github.com/Axosoft/vscode-gitlens#current-line-blame...
- WalterGR 5y ago
  That looks like an awesome tool. Thanks for the link.

interactivecode 5y ago

Next thing you know someone both edits and renames a file and you lose all your extensive documentation

kroltan 5y ago
Well, at least they will document why they edited-and-renamed the file!