[shakna]

To explain why a certain block of code exists. When the code came into existence is rarely that important. You just want to know why.

Why does the code fence against a particular circumstance you didn't think should be possible? Why does it call out to something you think is unrelated? Those questions can be answered by a proper commit message.

[kazinator]

Sometimes, in some kinds of projects, the commit messages looks like this:

  JIRA: #1234

  Adjusted the FOOBAR parameter from 42 to 73.

To know the "why", you have to read the ticket; you will not find anything in the git log.

[erik_seaberg]

Oh jeez, please do not make me run “git log” and then open a hundred tabs in an old bug tracker that may or may not still exist to figure out when a problem may have been introduced. I want code reviewers to insist on at least somewhat useful messages for us to skim at 3 AM.

[ArrayBoundCheck]

I set a breakpoint and run the test suite for that answer

[fragmede]

That answers what the code does, but not why it does what it does.

[tuwtuwtuwtuw]

So you never need to understand when or why a bug was introduced? Or you never need to understand why the current behavior as is it is?

[d3nj4l]

Why don’t you put that as a comment on the code?

[lexicality]

Comments are for why code is written the way it is, commits are for why the code is written in the first place.

You _could_ tag every line of code with

  // JIRA-123 The PM wants this to be blue

but if you did it would become unreadable and wouldn't be kept up to date.

[kazinator]

Because if 37 changes are done to the same 15 line function over time, the amount of comment material will dwarf the function. And most of it will pertain to historic versions of the function which are not what actually appears below the comment; a comment made 13 revisions ago makes sense for the 13-revision-old version of the function.

[d3nj4l]

You just update the comment?