HNHacker News
TopNewBestAskShowJobs

hmeh

159 karma · joined February 9, 2010

Contact: aaronjensen at gmail

Software Development Articles: https://github.com/aaronjensen/software-development/#software-development

submissionscomments
hmeh··on Does your test suite account for weak transaction isolation?
This and other concurrency problems often fall into the “you just have to know how to not get it wrong” camp. If you know to write an automated test for it, you probably know enough to reason about it and get it right. For very important things, sure, maybe write a test, but these tests are very expensive to write and maintain. It’s often cheaper to recognize (and train other team members to recognize) these scenarios and use a higher isolation level. Postgres makes this easy because serializable doesn’t come with a huge perf penalty (mostly memory, I believe).

I’m strongly in the TDD camp too, btw. So I don’t say this flippantly. I appreciate this article bringing further awareness to this.

Also, I cannot recommend partitioning (and event sourcing) enough to eliminate and simplify these problems.

Article on partitioning: https://github.com/aaronjensen/software-development/blob/mas...

hmeh··on Does your test suite account for weak transaction isolation?
Relevant, not all logs are ledgers. https://twitter.com/sbellware/status/1742653635387941099
hmeh··on Stop Saying "Technical Debt"
Totally agree that it has lost its meaning. We call things “incomplete work” that are, well, incomplete work.

I wrote more about it here: https://github.com/aaronjensen/software-development/blob/mas...

Also the advice in the article about noticing the issues and tracing them to their root is spot on. We record setbacks and mistakes in our work logs for our team to see and socialize common problems so we can address them holistically.

hmeh··on Subject-First Commit Messages
In case you are interested:

https://www.nngroup.com/articles/first-2-words-a-signal-for-...

https://www.nngroup.com/articles/text-scanning-patterns-eyet...

https://www.nngroup.com/articles/list-entries/

Commit summaries are typically viewed as lists (though not always, and in that case you often have more context, e.g., the rest of the message and the diff)

We optimize them as we would list entries in any other thing we design for human consumption.

Btw, we didn't refer to these specific articles when we made our decision, I found them just now.

I updated my article with links to these. Thanks again for the discussion.

hmeh··on Subject-First Commit Messages
> Ooookayy. I would not compare any technical decision in this space to that. A bit grandiose.

One has to be able to understand an analogy for the point the person is trying to make -- it's not an equivalence. Obviously most software issues don't rise to the level of life or death.

That said, let's try a few others:

- Waterfall

- DCOM

- CORBA

- Web Services

- Microservices (as implemented by web developers -- per-entity web api to web api to web api cascading failure)

- Monorepos (not globally, with sufficient support these can work)

- Devs shouldn't write tests

- Fat Model, Skinny Controller

- Write tests. Not too many. Mostly integration.

- Single Page Apps for all

- SCRUM

- Story points

Most, if not all of those were embraced by "most experts", but are now demonstrated problematic or at least are knowably wrong from fundamental design principles. Note that statistically speaking, "most experts" are, at best, early majority. There aren't very many in the Innovators and Early Adopters, and crossing that chasm is rare, and hard.

We have a history in our community of intransigence, repeating mistakes, and expert beginners being the most outspoken portion of our community. They are the ones that have the most to gain by blogging and self-promotion and there are significantly more of them than people who may have different things to say for good reason. Note that right now, I am speaking generally, not debating a commit message approach.

> Then... you disagree with the "of course", you said.

No, the "of course" was: of course no one I work with would make that mistake (more than once). It would be an extremely beginner mistake, and we would have failed as coaches on our team to not pair with a person long enough to help them understand how to write proper commit messages.

> I'm going to assume that's a dependency version change.

Yes, it's a pinned version for that dependency. You don't have any context on that particular commit, so it's not surprising that it's ambiguous.

> Most theories are wrong, even by experts. It's not even embarrassing to be wrong.

Indeed! I have been wrong many times in my career. Hell, I invented the "auto-mocking container" which, in hind sight was so stupid (and btw, my colleague you referenced warned me about it at the time -- he's always been a few steps ahead) that I never should have popularized it. Thankfully, it fell into the past along with IoC containers (for the most part).

I have plenty of other stories about being wrong as well, and as I've said elsewhere, if we find a better way to write commit messages we will do that. For now, from our analysis, the way we do it is best for us -- observably (I'll say that, rather than objectively, though I do believe we were as objective as possible in our analysis).

Thanks for the discussion.

hmeh··on Subject-First Commit Messages
sbellware may have more to add, but there isn't a name for it. We focus more on the "it" than the branding of it. We do use the word "continuity" to describe our goal: https://github.com/aaronjensen/software-development/blob/mas...

> The words "equipment log" and "work product" sound pretty unique.

We call them "material logs", as equipment logs are more or less a subset of those. Just think about the sheet in every bathroom at a store that says when it was last cleaned, or the clipboard attached to the factory machine that lists its maintenance record and problems. Or the patient record outside of the patient's door.

"work product" just means, the product of our work. Nothing special about that one, I don't think.

> Are Erl's SOA books and Yourdon's on OOP still relevant?

I haven't read either, personally, though I have Yourdon's book en route. We use the term "structural design" quite a bit, so I'm curious to see Yourdon's take on what they call "structured design". From everything I've read about it, it sounds very similar to a lot of how we think about things as it seems to be the basis for much of the coupling and cohesion thought in our industry.

I'd also recommend studying Lean (not Lean Startup, which has much to do with Lean as non-fat yogurt does).

hmeh··on Subject-First Commit Messages
> I like to be able to read the commit line following the sentence: "This commit shall ...".

I'd guess there's a near zero chance you do this when looking at (scanning) a list of commits. This is a mnemonic for writing commit messages in the commonly accepted style. If you do that in order to help you understand a commit message every time you read one, that may be a personal thing.

> Means nothing. Tells nothing. Is 1000 good or bad? No clue. Is it causing a bug? A performance issue? Was it 1000 before the commit or after applying it? Zero information. > Using the best practices the commit would read: > "Change default reader batch size to 500" or "Change default reader batch size to 1000"

You realized you could ask the same questions about the versions you put forward, yes? Aside from the "Was it 1000 before the commit..." which, on our team, would be such a ridiculous question it wouldn't even enter the mind. As I said somewhere else, the headline for a celebrity dying does not ever read: "Some Celebrity Is Sick"

> I'll pass and keep using the "best practice".

Works for me :)

> I look at how multi-million lines codebase like Linux or Emacs are doing it and use that as the authority. If it works well enough for these projects, it works well enough for smaller projects.

Linux and Emacs have completely different circumstances than most software projects. The idea that cargo culting their practices is good for "smaller projects" is exactly why I wrote my article on best practices. By the way, I contribute to Emacs and I don't find their particular commit message format good or useful. It's particularly onerous, redundant, and does not tend to provide useful additional information (in particular the mandated change log portions -- people do often supply additional information, which can be useful). I tend to find the devel list and bug list more useful for the context of a change, which fits with our experience as well with work logs and project logs.

hmeh··on Subject-First Commit Messages
> you acknowledge that you hold a minority opinion

An opinion being minority has no reflection on whether or not it is correct. See hand washing in the medical profession before it was understood, or batch sizes in the automobile industry before Toyota ate the west's lunch.

> And I find it dishonest to phrase that as "The psychology portion isn't subjective".

You can find it dishonest if you wish, but I'm trying to point to a body of knowledge I can't adequately convey in an article or a hackernews comment. I'm not trying to pull one over on you, I promise. As I said in another response, this is a design decision. Most design decisions are based on first principles, a-priori knowledge, expertise, a wide range of studies and observations over time, etc. If a person can't write down (convincingly) all of the tacit knowledge required to make the same decision, they are not being dishonest.

I'll say it this way: We made this decision based on objective factors. I do not expect everyone to be able to see our decision or our reasons in the same objective light and I'm not going to try to convince someone that doesn't. But telling me it's purely subjective is gaslighting, and impugning my integrity over it is just rude.

> You'd be surprised.

No, I wouldn't. I would be surprised to see it on our team, or any other well-disciplined team. This article is a tiny (and frankly pedestrian) part of our overall development process. I'm sure you'd disagree with just about everything else that we do as well, and that's OK as well.

> Oh, really? Do you have an example?

Sure:

mail package version is decreased from 2.8.0 to 2.7.1

This happened when we were forced to pin to an older version of the mail gem because of a regression in 2.8.0.

Note that the scenario you described: "(1.1.2 can be released after 1.2.0, yes, but that's not a decrease even if something was backported)" isn't relevant to our practice. We don't maintain multiple major/minor versions at one time of any of our packages. If we did, they would be on separate branches as the version number can only exist in one place (the gemspec) and the same exact rules would apply. That is, it wouldn't be a version decrease, it would be an increase from 1.1.1 to 1.1.2 on the 1.1 branch.

hmeh··on Subject-First Commit Messages
Again, I was responding to this particular text: "And the work does an action on the code." You can interpret that the way that you interpret it. I saw it as a part of a wider tendency in the development community and responded to it accordingly. Perhaps it wasn't what was intended. At this point, it's rather a distraction so I'm happy to concede that it is ambiguous and the author was likely attempting to describe the common "When applied, this commit will..." inferred prefix.

> It’s also rare to find commit message quality that is on the level of the regular contributors to that project

Good stuff, I'll take a look at it. Thanks!

hmeh··on Subject-First Commit Messages
I was responding to the author of the comment I was responding to, who was anthropomorphizing the commit itself claiming that it did something.

I agree that the person who write the code is irrelevant, though I realize that in a different way. I also recognize that it varies from Git/Linux/etc. We do it for usability and other reasons and one only needs to look at git itself to recognize that the original authors did not have usability in mind when designing it. What they built is incredibly powerful, but it's rare for usability and technical prowess to overlap.

hmeh··on Subject-First Commit Messages
Very much agree. I've seen it leak into conversation in slack too... "Hey, I have a question about JIRA123, should we use blue for the button?". There's no greater way to tell someone you don't care about their time than presuming to force them to look up work items every time you want to refer to something.

I believe that if teams look hard into the reasons they think that that practice is valuable, they will uncover even greater culture and process problems to address. Once they are addressed, they will no longer need them, and they'll even start to see the harm in them.

Most teams won't do that, however, and I will be dragged out to the town square for even suggesting it's possible (even though our team operates extremely well without this practice or anything resembling it).

hmeh··on Subject-First Commit Messages
> What's your evidence or supporting research?

We didn't need it. It was based on a-priori knowledge. For example, we don't write email subjects like: "Convey information about new release", or "Ask question about time off". We know from how the human brain processes content (eye tracking studies) that they scan in an F-shaped pattern. This puts emphasis on the content on the left. If the left side has no differentiation, this is, de facto, harder to scan.

You don't have to agree with me. As my colleague said, there are other, even more subtle things we are trying to convey and reinforce: https://news.ycombinator.com/item?id=38836919

> You skipped the step where "most important" is defined.

No, we literally do this every time we write a commit message. This is a usability issue. What is the most important thing to the reader?

> Ok. Specifier can be configured when constructing a store. Is it supposed to? Is it the state before or after the commit? Is this just context, and maybe this commit changes documentation to reflect that reality?

And yet, when all of your commit messages are in a consistent voice and mood, there is no ambiguity. Also, all of your questions are answerable from a self-evident perspective -- if you can rely on your teammates to care about your ability to understand what they write. Of course it's supposed to, otherwise why would I commit it? Of course it's the state after the commit, why would I talk about what was (How many newspaper articles about a celebrity's death have a headline saying they are sick?)? Of course it's not about documentation, it would say it was if it was. In short, you can make up as many holes as you want to poke through.

> You even say that reading a bunch of them is uncomfortable.

I said at first. See: familiarity bias

> What about the widget tests?

This is convention that one could argue requires memorization. I don't actually think it does, however, because of how we as humans interpret subjects/headlines.

> Are version numbers ever decreased?

They have been, and I hope it's self-evident how that commit message would be constructed on our project.

In any case, I'm not here to quibble about commit message formats. I documented ours and gave supporting rationale which is based on UX knowledge (and research, at the very least, see eye tracking studies). If you think that "Fix", "Fix", "Add", "Change", are the most important part of the commit message, then I'm not really going to be able to or even bother trying to convince you otherwise.

hmeh··on Subject-First Commit Messages
What if there was another way to handle things like #2? What if you got everyone that needed to be there in the same "room" and had a synchronous conversation in order to resolve all ambiguity?

We don't call them tickets, because we aren't "ticket takers" and we don't expect them to contain all of the information -- how could they, it's our job as implementers to discover and understand. They are work items, and they are placeholders for conversations. We use high-bandwidth communication to reduce, and often eliminate, the "back and forth" that is so common on many teams.

We keep logs of our work both on a personal and project level, which includes decisions from these high-bandwidth conferences. When we have stakeholders that are hard to get meetings with we schedule a regular cadence with them so we can get their time at least once a day/week/whatever.

hmeh··on Subject-First Commit Messages
Point of order, PRs get lost too. Git repositories can be moved from GitHub to GitLab, or tar'd up and sent in an email when a project gets handed off to its new maintainers. We try to keep things that matter in text files in repositories. We will always own those. Tools are just tools for transient activities (work items in our task tracker are just placeholders for conversations).
hmeh··on Subject-First Commit Messages
I'll offer a perhaps controversial perspective.

What if only people that had context did reviewing? As in, what if when someone needed a review, it was their job to ensure that the reviewer had the context necessary. That is, it was "push" rather than "pull".

What if a team's process was set up in such a way that separate phase-gate reviews were not typically necessary. That is, the team tended to work in pairs where there was constant reviewing going on, and the team was practiced at pulling people in when necessary to review specific parts, e.g., things they had never done before or needed additional guidance on.

Do we all remember waterfall development? Where PMs would write specs, then they would throw those specs over the wall to devs, who would then throw code over the wall to testers? Does anyone feel like, perhaps, we've done it again with pull requests and we've started favoring asynchronous hand-offs, rather than one-piece-flow?

hmeh··on Subject-First Commit Messages
Author here. I chose two real sets of commit messages rather than to fabricate one. Fabricating one may have made the second list easier to scan -- you'd already know what you were looking for and you would have some familiarity with the content. In any case, it's certainly not a perfect experiment or demonstration.

The specific function/variable names do not often make appearances in our commit messages (though they do sometimes, as do class names). They do, however, make very clear appearances in diffs. Commit messages stand on their own for their own purpose -- it's an index, and indexes are for scanning. If you need to read further, you zoom in.

Also, I wasn't trying to say to "use longer sentences for everything," where did you get that from? I offered some specific clarifications on how we write some common commit messages, and they may be longer than some alternatives, but our reasons are for clarity and consistency. We don't mind slightly longer commit messages, in large part because the first few words tend to be the most important.

hmeh··on Subject-First Commit Messages
Author here. Thank you, updated.

We don't tend to put much in the commit messages themselves. The code often speaks for itself (and if it doesn't, it isn't likely that the author would have had much more to say about it at the time, as our norm is to comment "why" when necessary). We also have work logs we can refer to that sometimes have the why, or at least some of the context for the work we are better trying to understand.

hmeh··on Git Things
Honestly, we have so many repositories and such high communication between work cells that merge conflicts are exceedingly rare.

If someone did change something out from under me, I could very well see myself doing my work over on top of theirs, and a rebase may help with that, but I would certainly try to merge first.

I tend to use rebase solely when I specifically want to rewrite history so as to pretend it was different than it was.

Thanks for engaging and discussing!

hmeh··on Subject-First Commit Messages
Indeed, and since we don’t do pull requests (we pair, mob, and/or do live code reviews), the after-the-fact git blame or the git log to see what has changed recently is what tends to matter.

I agree that when I did PRs I didn’t tend to care about the commit messages when I was reviewing them, but even when I did do PRs I cared about them later any time I was trying to understand how, why, or who forensically.

hmeh··on Subject-First Commit Messages
Oh, we’d be fine without it. It just augments.
hmeh··on Subject-First Commit Messages
I'm trying to imagine my commits coming alive and doing things to my code. I think you may be taking the "When this commit is merged..." thing a bit far, as commits don't actually do anything. They just are. We don't tend to do ourselves any services by anthropomorphizing aspects of our work. I'm happy to concede that we see things very differently.
hmeh··on Subject-First Commit Messages
Got it, thank you for the links. As I suspected, we just don't have these problems. Rather, we have other things that cover these needs when they arise that we have full ownership of (i.e., it won't matter if our issue tracker is replaced).

Specifically those are work logs (individual daily logs), project logs (logs for larger projects which may consist of a work cell of a few people and several work items), material logs (logs for specific equipment, virtual or otherwise), work in progress notes (notes for ongoing initiatives, including checklists, etc.), etc. They are all text files contained in git repositories that are always available for reference. We can also refer to Slack conversations, but most of our conversations are done live so as to avoid hand-offs, so we must rely on recording of decisions by folks on the team.

We use our work tracking system just to track work -- placeholders for conversation.

My colleague wrote in more detail about what goes into our work and why issue numbers don't even enter our airspace: https://news.ycombinator.com/item?id=38836919

hmeh··on Subject-First Commit Messages
It was a design decision, and like most design decisions, it was based on first principles and a-priori knowledge. If we had to base all of our design decisions on data and benchmarks, we wouldn’t be able to design anything. I can assure you, that if a better format with better properties came around, we would likely switch to it (assuming we accounted for switching cost and the variation we would be introducing).
hmeh··on Git Things
I tend to think it's better to have merge conflict changes be in a merge commit. That way the original commits are still present and if there was a mistake made, it'll be in its own commit. Contrast that w/ rebasing, where the original commit goes away and gets modified to account for the conflict. Compound this w/ the fact that when you rebase you may have to resolve related merge conflicts in multiple commits, and I think rebasing to deal with merge conflicts is the opposite direction of what I would recommend.
hmeh··on Subject-First Commit Messages
Author here. We have actually managed to use the same task tracking tool for the three years our project has been running: Linear. We don't do pull requests, and we don't put our work item number in our commit messages.

I can count on zero fingers the number of times I have ever wished I had this.

We do, however, keep daily work logs (each person submits them) so we have a log of everything that everyone worked on. We have Slack history, which is sometimes referred to.

I'm curious what folks find this useful for. What are the scenarios where one has to refer back to an issue from a commit?

By the way, I also have the experience of inheriting a code base where the commit messages were mostly (or just) issue numbers. Guess what I didn't inherit? The issue tracker. The commit messages were useless to me.

hmeh··on Subject-First Commit Messages
Author here. You're well within your rights to believe it is personal preference, but it's somewhat hard to refute the fact that it's easier to scan lists when you put the most significant (i.e., the part that varies the most) first. Imagine if every item on Amazon's list of products was of the format: "Product for purchase, Headphone, Sennheiser Momentum 4"
hmeh··on Subject-First Commit Messages
Author here. The psychology portion isn't subjective -- things are easier to scan if the more important part is first. One would have a hard time refuting that. Also, there is some familiarity bias that comes into play when reading a commit message style that is foreign, so the experiment I offer may not be super compelling. We are used to what we are used to, and that takes some time to overcome. I know it took me a while to overcome it both in writing, scanning, and reading them. It was worth it for me and our team.
hmeh··on Subject-First Commit Messages
Author here. Commits aren't actions -- they are a log of an action being taken. You, the committer, are committing. What you commit, goes into a commit log. We choose to make our commit messages describe the change, rather than the person that made the change. It's about the work, not the worker.
hmeh··on Subject-First Commit Messages
Author here. I don't know that arbitrary is the right word. They were decided, and generally found to be superior to alternatives. We stick to them so as to avoid special variation (https://github.com/aaronjensen/software-development/blob/mas...).

For example, correct reinforces the notion that things can be wrong, mistakes can be made, so we correct them. This is essential to our team culture.

"Rather than" came from Eventide's norms and I wasn't there when it was discussed initially. It works for concepts other than renames, so it is more flexible, but I can't say that was the reason for the initial decision.

hmeh··on Subject-First Commit Messages
Author here. Thank you! I agree that there can be plenty of bike shedding about them, which is why we have an approach that is based on human psychology and can be backed up in that way. We don't often put too much more in the content of a commit message -- the diff, plus the repo it's in (we have many repos) tell you most what what you need to know.

If you want more context, every team member has a daily work log that is available to the entire team, so you can see more about what they worked on and why in that work log.

← PreviousPage 3 of 5Next →