[knappe]

I can't disagree with this more. Good commit messages are just so, so, so important. Especially when I'm triaging an issue and have no other context than the code itself. I want to know not the _what_ which the code gives me, but also the _why_ which is what the commit message provides.

[swanson]

That's fine. I think your opinion is the majority opinion (at least online). It just does not match my own experiences of reality.

You can and should value practices based on your context. But I will be the asshole and ask if writing good commit messages is "so, so, so important" -- what things are less important? Is it more important than a good test suite? Well factored code? System documentation? Capacity for senior staff to answer questions? These things cannot all be so important and, in my experience, worrying about crafting amazing commit messages is way down the hierarchy.

[realbarack]

I'd certainly rather jump into a codebase with a great test suite and crappy commit messages than a crappy test suite and great commit messages. But these are apples and oranges. Keeping a great test suite is a constant fight against tech debt, and testing things properly can be harder than the actual implementation.

In contrast leveling up from the terrible "WIP WIP do the thing" to something slightly less awful takes maybe an extra 1-2 minutes per commit. And every time you do it you're doing your future self and future co-workers a huge favor.

[lowercased]

There's a trend towards automation built around 'commits' that encourages this sort of thing.

"WRITE BETTER MESSAGES".

but put WIP in the title so we know not to review it.

but ... do commit often, so we can get builds out. put WIP in the title so we can decide to build with tests or not. or something.

Tying automation steps to 'commit messages' is begging for "WIP JUST COMMITTING TO GET A BUILD OUT" messages, which people then complain about.

[majormajor]

You're starting to contradict yourself a bit, I think.

Will I disagree that good test suites or well factored code or systems docs are more important than commit messages? No.

However... most projects do not have those things and most developers on those projects are in a "I don't know what I'm missing" sorta state where they don't bother adding them. Exactly like you point out for good commit messages.

So if 95% of projects have inconsistent and incomplete test suites, never-refactored spaghetti code, and almost no system docs, that doesn't mean we should tell people not to try to do those things. In the same way that the existence of poor commit messages doesn't mean we shouldn't try harder.

The nice thing about commit messages, being a small and simple thing, is that it would be much easier for someone to learn how to write good commit messages overnight than to learn how to write a good test suite, or to refactor their code.

[swanson]

It's commendable to strive to improve. I agree that 95% of projects are a mess. I don't think there is value in writing good commit messages in those environments, even if it is easy. If you're going to spend 30 minutes writing a super awesome commit message, I'd rather you spend those 30 minutes on improving the code or the test suite or even writing the awesome commit message in the JIRA ticket.

If you've reached the point when the next "optimization" you can do is to work on your commit messages, that is awesome.

[majormajor]

I'm picturing 1 to 2 minutes on the message, which is why I don't see it as competing with refactoring or test time.

I also think spending paragraphs on "commit message standards" is overkill. I don't care about full stops or capitalization or anything, I just want to know some basics: "What is this fixing or adding. Why is it done this way. Are there any special considerations that kept it from being done a different way?"

You bring up a good point about location, too; i don't particularly care if the info is in a ticket or commit message or a pull request, as long as I can get to it)

[idolaspecus]

I think they can in fact all be "so, so, important". Maintaining a large, long-living, complicated codebase is a genuinely difficult problem involving a plethora of actually critical components and processes.

[dllthomas]

I find old commits more useful than old commit messages; seeing what changed in tandem can be hugely informative - doubly so when tests were a part of it. But good commit messages can still be a big help, for sure.

[phailhaus]

The why should not be in your source control, the why should be in comments in the code itself. There are many reasons why a line of code may have changed, and it's unreasonable to hide important contextual information in a commit and ask engineers to waste time digging through the commit history to find the initial change (which may have been in another file!).

[wcarss]

Comments almost always become lies with time, because code changes and nothing enforces that they are correct.

Having commentary built into the artifact that introduced the change ensures your commentary applies to the specific change introduced. It's then possible to tell why someone did a specific thing, and also to tell how things are today, and to decide if that justification still applies, or if things no longer match the description.

If you dig around a little bit, using e.g. the git pickaxe (-S), or github's excellent blame browsing tools, it's not that time consuming and you might find out some pretty surprising things.

[phailhaus]

> Comments almost always become lies with time, because code changes and nothing enforces that they are correct.

Maintaining comments is part of the job of the software engineer, to keep code understandable and maintainable by others on your team. If your comments are constantly going out of date, then either:

1. The team is not putting effort into keeping comments relevant for each other.

2. The comments are too far away from the code that they are referring to.

There's definitely a balance to strike between too many and too few comments, but comments are extremely important.

Commit messages describe why the code _changed_, not why the code is currently implemented in the way that it is. Those are two different pieces of information, and the latter should not be hidden away in a commit message that you have to go searching for. And if that code came from another file, it's extremely difficult to trace it back to the first time it was written.

Not only that, but how would this even work with the "atomic commits" requirement? Most of the time you can't change a single line and create a commit message explaining why that line changed, because it's not atomic. That line change happens in coordination with a bunch of other changes. How do you explain why one of those lines was implemented a certain way in your commit? It just doesn't work.

[idolaspecus]

I agree that maintaining comments is difficult and that they tend to drift. A good way to mitigate this problem is to explicitly include checking comments as part of the code review process.

I'm not saying you did this, but I think that most people who point out little issues with the mundane processes within software development haven't yet grokked the dev process in its totality. Commit messages, code reviews, comments, documentation, unit tests, design patterns and idioms, all these practices' strengths and use-cases compensate the others' weaknesses. I.e. to basically any gripe (again, not saying you griped) like "process X isn't worth it because of some maintenance issue" there's an answer along the lines of "well that's what process Y is for". Together all these processes produce high-quality codebases but when you lack one or more of them the whole thing falls apart quickly.

[pydry]

The why is typically better provided by descriptive comments and tests. I'd rather people put more effort into those.

The exception is ticket numbers - it's sometimes useful to be able to link commits to tickets to see the context of a feature, especially since it's cheap to do.