Beware the Siren Song of Comments

  Is this a matter of insufficient knowledge of my IDE?

After writing this, I realized that it a symptom of exactly that: I'm not fully savvy with PyCharm/IntelliJ, my Python IDE of choice. I'll run down the ways I know of to access blame history (in case others don't know it exists).

1) Git -> Annotate: This is almost exactly what I wanted!

This gives a `git blame`-like column next to each code line, and clicking an item will show a summary of the commit, including both the commit message and fields modified. I can right click one of the annotations and select "show diff", and can even see the modifications to any of the files in the commit if necessary.

Unfortunately, this depends on a commit message explaining why that change mattered, AND on it being the most recent changes to those lines. Moreover, it doesn't show the full history of changes for those lines, such as if Alice added the real change, and Bob just did some whitespace changes.

I can find such information (with effort) using `gitk` or other git log browsing tools. If the most recent change (shown with git-blame) doesn't have what I need, I basically need to look at all of the changes for this file, going back from that commit, and see if I can find the one with a message that explains why ${hackity-hack} is necessary.

2) Right click a file tab or in the editor, and select Git -> Show History

This is a faster way of browsing the commit messages, but doesn't give enough information for me to tell whether that change was the one that affected the lines I care about. If it showed the diff of what the commit changed in my file, it would be more informative. (This is what gitk shows, for example.)

As far as I can tell, neither of these options is as comprehensively informative as using `gitk myfile` and backtracking from the commit that `git-blame` (or PyCharm's Git->Annotate feature) lists as the most recent change to those lines.

If comments don't describe what Is Happening or What Should Happen, they should be changed. This is much harder than maintaining unit test coverage, but I think the information is still very valuable to have in code comments rather than solely in commit messages. (It is certainly valuable to have them in commit messages as well, of course, as that documents how you felt at the time.)

I agree. I use TODO indicators as a code smell for things I forgot to add before making my pull requests, but I also see them as valuable reminders for future needs.

Sometimes there's a quick-but-less-generalized way of solving something, and you know there's a more elegant way of doing it, but for now you need to get something working/fixed and don't want to make sweeping changes.

Your immediate change might be to add a way for users to see that X is finished. A useful TODO message would be something which explains what you're doing

  # Tell users when their Solve-My-Foo is done
  # (Currently done in an ad-hoc way)
  # TODO: Add a notification infrastructure so that 
  #    arbitrary components of the apps can present
  #    notifications of Important Things
  #    e.g.:
  #    - celery job is done
  #    - a thing you've subscribed to has changed
  #    - a report/download/etc is ready to be retrieved

Building such a system might be overkill right now, if this part of your system is the only one that uses it, but a TODO message helps me see (the next time I make changes to it, or try to extend it, or use it as a template for reimplementation elsewhere) that there's more than one place we need this feature, and so it might make sense to plan/do those more comprehensive changes.

The hard part IME is keeping your audience in mind.

Your future self? Your coworker who might be hired next month? Your past self who would have wished to read said comment?

Who is the audience for the comment?

I really dislike his notion of using the commit logs as the correct place to explain your code. First, it means that any time I need to find out why something is being done in code I need to leave the code and switch from my IDE to my source control. Second, most tools like blame will only show the most recent change. Minor fixes and changes happen all the time. What are the odds that the explanation I want will come up instead of something like "Fixed a typo". Third, what about code from other branches and external code drops?I may be using code from somewhere else and not have access to the full history of changes, just stable versions. Fourth, what happens when you change source control? If all of the comments are in the Git commit logs that'll be a big problem if the company switches to Perforce.

Instead of just making meaningful commit logs part of the code review process why not make "reading the comments" part of the code review process?