[afarrell]

> Think of it like a short email that explains to your (future) colleagues and future self

Note that commit messages don’t live with the code. If you find yourself writing why something should be in the new state, consider putting that “explain why” as a comment next to the code, so anyone’s text editor can read it.

[jerieljan]

Hmm, I think it depends on the case. Sometimes it's appropriate to leave comments on the file, while sometimes trivial changes don't need to be mentioned and explained only at a commit message.

Oh and while it doesn't "live" with the code, I can at least look up a line in question and see which commits have changed it, along with their commit messages.

[Sir_Substance]

>Oh and while it doesn't "live" with the code, I can at least look up a line in question and see which commits have changed it, along with their commit messages.

The first job I had, I was working on software that had originally been developed by a software engineer but had then been passed to the stewardship of non-programmers.

Originally, it had been checked into CVS (yeah, it was that old), but the non-programmers didn't know what that was or how to use it, so when they started making experimental edits, they just copied the source folder to a new location and labelled it "NEW <project>". By the time I got involved there were over 200 of these folders on the network drive, it was unclear which one if any represented the head revision, and the machine with CVS on it had long ago been lost and existed only as a legend.

This wasn't insignificant software by the way. I don't feel like telling you exactly what it was, but it was an intense physics simulation and it has quietly impacted probably around a million lives over the last few decades.

The point is, don't assume your commit messages are as permanent as your code, they're not. Non-developers just barely grasp source code being important but they don't understand VCS history /at all/. Put important comments in your code.

[u801e]

> By the time I got involved there were over 200 of these folders on the network drive, it was unclear which one if any represented the head revision, and the machine with CVS on it had long ago been lost and existed only as a legend.

Fortunately, DVCSs don't have that problem because the meta-information is stored in a folder within the source. So unless the non-developer deletes that folder in every single project, then the information won't be lost (but it wouldn't get updated either).

[Sir_Substance]

That actually depends on how it gets copied and pasted.

I can think of at least two ways off the top of my head to move the source from folder A to folder B while leaving hidden folders behind. They both assume you're using a graphical file explorer, like non-developers are likely to do.

[mAritz]

I think a good way to look at it is to think of "explain why" in commit messages as explaining why the code was changed from the previous state to the new state. This may need explanations on how some of the code works, but it doesn't have to.

The "explain why" that explains how the current code state works however should sit next to the current code.

[afarrell]

Yep, it’s definitely a thing to exercise technical-communication judgement about.

[u801e]

They're associated with a line with a file. git and other SCMs provide tools that allow you to see what commit is associated with a given line, what the state of the file was at the time the commit was made and when lines in that file were removed subsequent to that commit.

> If you find yourself writing why something should be in the new state, consider putting that “explain why” as a comment next to the code, so anyone’s text editor can read it.

The problem here is that there's no guarantee that the comment gets updated when the code does. Whereas, a commit is always associated with the code at the time it was written. If the code is changed, then that old commit is no longer associated with it.

[afarrell]

The guarantee would be the same guarantee you get when you update a codebase: that you (and code reviewers) look at the nearby code and see if it still makes sense in the context of your change.

> if the code is changed, then that old commit is no longer associated with it

Right, this is my problem with putting “why” always only in the commit message: Sometimes the “why” is both durable and shouldn’t be buried by later commits. Suppose you refactor the code: you’ve put it in a new place or you add trailing commas or you replace positional args with keyword args. Now the most recent commit is the one that explains that transition. Code is a UI that a future engineer will use to understand the system. An important prose explanation is part of that UI and you might decide it should present itself as an affordance.

This is an exercise of technical-communication judgement: I’m proposing that you should ask, where the explanation should go. Should it be hidden for those looking through the history? Probably. Should it be clearly visible alongside the code? If it is important and durable.

[lugg]

... The answer to "why?" goes in the tests.

Use commits for an audit trail of ticket numbers, urls, and playing the blame game.

Use comments for expressing the inferred. // That which is not explicitly stated.

[afarrell]

Unrelatedly: `tig blame` is a better UI for exploring commit history than `git blame`.

[chrisan]

To take the example from this guide

> Increase left padding between textbox and layout frame

You would put that in your CSS file so anyone's text editor can read it?

Besides, what text editor doesn't support `git blame`?

[afarrell]

No because I would ask myself “Is this a description of why the end state of the code needs to be this way?” to which the answer would be “no.”

I don’t think you’d add a comment like

/* 5px optimizes visual balance */

Either. Its just too small a detail that it isn’t worth directing your reader’s attention to that.

My proposal isn’t a rule, but rather a question to ask yourself and then to exercise your best technical-communication judgement about.