Hacker News Reader

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

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.

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

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

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.

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.

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

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`?

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.

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.

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.

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

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

Nobody questions it is important to write clear commit messages. The issue is being nitpicky about what exact form is being used like whether to capitalize first letter or not.

When I look at the repository I am happy if I can understand the messages at all. It's challenging to get people to group changes in a logical way so that the commit makes sense. I am not going to pick on somebody because he used wrong tense or did not capitalize first word of the message if the changes are grouped logically and the commit mentions the correct ticket and purpose of the commit.

I feel it reduces cognitive load, like proper formatting of code.

Do you enforce consistent code formatting in your codebase (using CI, maybe)? If so, why wouldn’t you do that with commits?

Because the commit messages, just like email messages, isn't part of the product. They are part of communication between developers. You could as well require people on mailing list to never top-post and always spell correctly, to reduce cognitive load. Some people actually do that, but they are pretty annoying. :)

I'm in that camp that doesn't enforce consistent styling in code or even particularly believe in the value of linting at all! ^_^

I'm pretty much just echoing what others have said, but when I look back at the things that have caused problems / mattered in a codebase, things like formatting are generally ranked an order of magnitude below everything else.

If people care, I'm happy to oblige, but it always seems like a missing the forest for the trees kind of thing.

I used to be in the camp that cared a lot about formatting, but over time realized that it's more my OCD than any practical reason.

At this point, the only reason why I like consistent code formatting rules is because they prevent bickering between people who have strong opinions on how things should be. When there's a rule, even if people don't like it, they abide by it. When there are no rules, everybody who thinks that there should be rules starts bikeshedding what they ought to be.

But as far as code quality goes, I don't think it matters much.

If that's the case, why have standards when it comes to writing code, e.g. when to use camel case? Why have styles at all for writing in a language like English that tell you how titles should be formatted? Consistent format and structure reduces cognitive load IMO, because it breeds familiarity. Also, Git itself uses the imperative mood whenever it creates a commit on your behalf. Consistency is good.

> The issue is being nitpicky about what exact form is being used like whether to capitalize first letter or not.

How many code bases have you worked with that don't bother enforcing some type of standard with spacing/usage of tabs, indentation, variable names, method names, import order etc? People don't typically view those rules/conventions as nitpicky. Why should that change with commit messages?

People absolutely do question if it is important to write clear commit messages. I've had quite a few conversations where people have said things along the lines of "why do you even care? no one ever looks at the commit meesages".

Also it's a good litmus test for whether you really know what you changed. If you can't describe what you did in a couple of lines, you either did too much or lacked clarity.

I second that. I find that it helps junior dev find the sweet spot in commit granularity.

Commit messages are a poor place to document code because they don't stay with the code. If the code isn't obvious, comments work wonders and often make the commit message more focused on documenting commit history not actual code.

I agree that when writing confusing code, it is best to add a comment to explain it. However, in cases where the line isn't commented being able to `git blame` a section/line and read the commit message it was part of to understand the context for it can be invaluable at time.

That's a good point. I think git blame is underutilized in my world.

These are two different things.

A coment in code describes the state of the code as it is. A commit message describes a change in the code, a delta.

A comment in the code can do both, and it should. You should explain why your code is the way it is, not just what it does. Anybody can see what code does by just reading the code.

There's still a distinction between describing why the code is the way it is, and why it evolved the way it is over time. The latter is what commits capture.

Commit messages are great for explaining the order in which things happened and talking about changes that apply to disparate pieces of code.

I would still argue that comments should explain why code has changed over time -- comments should provide context for someone editing the code, which can include descriptions of what the code used to do, why it has changed, why it hasn't changed (what was already tried and why it wasn't good enough), what else would be impacted by a change, and information about the quality of the code (is it a quick hack, or has it been optimized extensively?)

Naturally you don't need to supply all of this, and if the code is changing very frequently it might be easier to put that stuff in a commit message. (It also helps when you use small, pure functions, because they tend to not need much context to understand.)

> Commit messages are a poor place to document code because they don't stay with the code.

They actually do stay with the code only as long as the code is present in the code base. The code can be updated independently of its associated comment, but the associated commit message will change.

They stay with the code as long as the code is absolutely untouched, which often is a lot shorter than a comment about code remains relevant. Code gets moved, reformatted, ... without details about it becoming stale.

Unless you have large chunks of code moved around wholesale, you can usually track all commits that touched a particular line of code. I've done that while debugging codebases that were over a decade old. And seeing those commits was incredibly helpful, despite the code itself being heavily commented.