4 ms·

I've been a Software Engineer for 15 years now... 10 years in the industry as a systems engineer before that. I sort of agree but what I try to do is put more

I've been a Software Engineer for 15 years now... 10 years in the industry as a systems engineer before that. I sort of agree but what I try to do is put more comments and documentation in the source code directly. The problem is that commit messages are usually hidden only when there's a problem. Comments are there for the life of the code. The problem with comments though is that they could go stale and something could be refactored. I try to put them directly on methods/functions more and not on specific lines of code. If I have to document a line of code it probably is a sign that it should be a function/method itself as it's a bit too funky to just stand alone. Commit messages are GREAT for tracking down when something is broken though. Would be nice to have your IDE take your code comments and make commit messages for new methods and the documentation for that method/class.

iudqnolq 7y ago
Jetbrains can be set to show you the last commit message that modified a chunk of code. I assume there's a way to do this in vim/emacs for the sufficiently motivated as well.
- morelisp 7y ago
  This is basic functionality via `git annotate` (which goes back, at least, to `cvs annotate`). It is also built into Emacs as `vc-annotate` (default `C-x v g`), though `magit-blame-addition` is a better option for projects using git.
  - iudqnolq 7y ago
    Awesome. Was missing that in emacs. Magit continues to surprise and delight me.
lhorie 7y ago
It doesn't need to be an either/or affair. Often times, I'll add a comment to a particularly tricky piece of code, but then also comment in the commit message (and then again in the PR in Github for the code reviewer) Often times, even a copy-paste is better than nothing. Better to over-communicate
jfultz 7y ago
My editor (Sublime + GitGutter plugin) is set up so whenever I click in a certain line of code, it displays a hint out to the right with the summary line of the most recent git blame on that line. It's pretty fast...maybe 1/2 second delay. I've found this really, really useful. As you say, commit logs can hide unless you're looking for them, but very often, the most recent blame (and even just the summary line of that blame) gives me really useful information.

iudqnolq 7y ago

Jetbrains can be set to show you the last commit message that modified a chunk of code. I assume there's a way to do this in vim/emacs for the sufficiently motivated as well.

morelisp 7y ago
This is basic functionality via `git annotate` (which goes back, at least, to `cvs annotate`). It is also built into Emacs as `vc-annotate` (default `C-x v g`), though `magit-blame-addition` is a better option for projects using git.
- iudqnolq 7y ago
  Awesome. Was missing that in emacs. Magit continues to surprise and delight me.

lhorie 7y ago

It doesn't need to be an either/or affair. Often times, I'll add a comment to a particularly tricky piece of code, but then also comment in the commit message (and then again in the PR in Github for the code reviewer) Often times, even a copy-paste is better than nothing. Better to over-communicate

jfultz 7y ago

My editor (Sublime + GitGutter plugin) is set up so whenever I click in a certain line of code, it displays a hint out to the right with the summary line of the most recent git blame on that line. It's pretty fast...maybe 1/2 second delay. I've found this really, really useful. As you say, commit logs can hide unless you're looking for them, but very often, the most recent blame (and even just the summary line of that blame) gives me really useful information.