[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.