Subscribe
Share
Share
Embed
Matt and Chris talk about detailed commit messages and try to answer the question "do we need them?"
You Ain't Gonna Need It, the podcast where we look at software practices and tools and ask: "do we need it?"
Chris: And we're live.
Matt: Hello. Hello.
Chris: Hello. I think it's recording. It shows me a little red recording light and says "REC", which I assume is short for recording. So I think we're recording.
Matt: Yes. Or "recreation", because this should be fun.
Welcome to YAGNI. Today I'm joined by Chris Toomey. Chris is the CTO of Sagewell Financial, which builds financial tools for retirees. Chris's formative years in software were spent at thoughtbot, a consultancy specializing in Ruby on Rails. Chris is someone I really admire because he holds a lot of well thought-out positions when it comes to building software.
On today's season premiere of YAGNI, we talk about: whether or not we really need good commit messages, pedantic best practices and rules, if we should be making TikToks for our Pull Requests, Big Consulting PsyOps, and I challenge Chris to a game of Russian Roulette. Hope you enjoy!
We are here today because I wanted to talk about, on this podcast some things that we do in software. And, I wanted to ask this question: "Do we need it?"
"Do we really need this thing?" And I think the answer, every episode, is probably going to be, the answer that we often come to in software, which "It depends". There is maybe not going to be a "yes" or "no". So I made a tweet and I said " what software virtue is actually the most pointless?", and my vote is writing detailed or excellent commit messages. Chris, what is your initial, reaction to that?
Chris: Well, I have sort of a meta reaction, which is when you tweeted that I saw it and I was very close to "replying on the Internet". But I tend to bias towards positivity or more, like if you look at my Twitter feed, you may think that I am an overly optimistic sunny individual, which is probably close to the truth.
But it's mostly because I find Twitter to be, it's very easy to, to bend negative or to, there's less room for subtlety and nuance on Twitter. So I tend to keep my hot takes a little more constrained. And so when you've reached out on this particular topic, I was like, Yes, I absolutely wanna talk about this.
Cause I think a podcast is a great format to dig in more deeply to these sort of things. And then to the more general topic of sort of looking at the ways that we work and asking the question, do we actually need this? Is this serving us? Is this the right trade off of costs vs benefits, I think is a wonderful sort of framing for thinking about all the work that we do because it.
The work that we're doing is always changing the processes, the best practices, et cetera, all of that. Again, so, love the question, love that we're here chatting about it. And it's interesting the way you phrased the question now to actually get to the specific question that you asked is, do we need it?
Do we need to do this thing? And so the answer is, do we need it? No, we, we don't need it. But I would argue that a, there is a lot of value in it. And in particular, there is a wonderful blog post by a former thoughtbot, and good friend German Velasco, that is called, "Write Good Commit Messages by Blaming Others". And so the idea in that blog post is : a lot of people talk about writing good commit messages, but the question is like, why? And Germantalks through both the mechanics and the actual practice of "git spelunking". When you're on a given line in your text editor, how can you get back to the git history that is associated with that?
And I personally do that semi often. Medium often is where I'd go with not, not every day...
Matt: Medium often, What does medium often mean to you?
Chris: If I'm being honest, it's probably like once every 10 days. Maybe it's once every week somewhere in that space. Really depends. It depends on the, the part of the code base. But whenever I'm looking at something like, Huh, that's why is that line that way?
If I'm able to just quickly hop into a commit message and see sort of a story from the developer who wrote it, as to the why of that change, then I find that incredibly valuable.
Matt: Yeah. It's, it's interesting and that I, I don't know if I would even call that medium often. That seems like very frequent, I guess...
Chris: I might be overestimating now that I, as I'm saying, I'm like, Is that actually true? I don't know, but it's definitely something that
Matt: Yeah. Something that you are doing, you know, once every, or like you're doing it a few times a month, it sounds like.
Chris: I I think so, yeah, less so now. I, I write less code now, so, I'm in the editor, or at least I'm writing or, working with code less than, I have historically, so that that number has dropped. But historically, that was definitely something I did on the regular
Matt: Yeah. At the, at the, the peak of your, you know, your development, you were reaching, you were reaching, I guess you were reaching for the, I'll say the more advanced features of git to navigate the history of files. And in doing that, you found that detailed commit messages were helpful in doing that.
Chris: Yes, or, or gave me a reason. You know, if there's a story there, then I'll go looking for the story. But there's a bunch of things that need to all be true for this to work out. One is I need to work on a team where we value crafting those commit messages. So like if there's just noise in the commit log and it's like typo, WIP, WIP, WIP then that's not gonna be useful.
So I tend to prefer squash based type workflow such that the final commit that makes it into the mainline branch is one that is made up of commits that are meaningful, that are sort of, tell a story along the way. The other thing that there's one like, lower level granular thing, but as we've started to adopt more like auto formatters and things like that, those commits can just completely ruin this.
But it turns out git has a feature for that with, I think it's like, "git blame ignore-revs" is the name of the file by defaults. And so you can say, Hey, get this one. This is just a formatting one. Don't tell me about that. If I try and get blame on a given line. And so that is, that's more for like hopping through history, but that is super useful
Matt: Right, because. If you don't do that, then you end up with, at some point in the past, some commit where you moved, you know, moved folders or changed your white space settings or something. And like you, you kind of lose the, you lose the connection, in some kind of meaningful way. So you can only step back, you know, five revisions and then you know that there's actual other history, but because, you've lost the linkage there, you can't get back that far.
Chris: I'm actually looking right now at the Sagewell repository. So we have one core repo, one mono repo. So, well, it's not a mono repo, it's just the one Rails app repo for Sagewell, and there are 13 entries in the git blame ignore-revs in the, I think it's, I think the repo is like 16 months old or something like that.
So we've done a bunch of these and we value the ability to tell git to just kind of ignore them.
Matt: The one thing, this is sort of unrelated, but it kind of reminds me of, is like having the history of the migrations in your rails project. And like at some point, you can like squash them down and it's like, we don't, we don't care about that. I'm kind of wondering like, what would, what would be your take if I said that, like, the git history should get collapsed every so often and so, if you're spelunking that far back, then it probably doesn't matter. How far back is useful versus like, you know. Yeah. It's useful to know the software as it was six months ago, but like six years ago? Has so much changed that just the code is not gonna be enough or is like potentially misleading? This is something I would run into a lot with, like when I was working on client work, it's like you could have the, the whole history of the project, but I'd say it, it was like almost always we just care about like what it is right now and like what we're gonna do to change it going forward.
Chris: Yeah, I think the current version of it is 90 plus percent of the value and the further, like the history decays as well. And so there's a lot of utility I think in capturing that and the commit messages because that decay happens very rapidly. And if we can clinging to a little bit of what was true at that moment in time that we wrote this given line of code, I personally think there's a lot of value in that.
But, I would say I rarely find myself looking back multiple years in a history and finding valuable, useful, relevant piece of information there.
Matt: Yeah. The other thing that kind of comes to my mind is like, I think my opinions would be a lot different if I were working on like a library or some, some piece of software like that where you actually, like I I, you would actually have more cause to go back and, and time and like look through the history of why some change was made versus a lot of times in like application development, it might be good to know like why this thing changed.
But ultimately it's like, well, now we want it to do this and it doesn't really matter. That it, you know, it, it used to that and we changed it. Or you know, we had this great history where we go back in time through the code and say, Yeah, at this point in time we made this decision. Because like, it might be that, like right now, like some executive is telling you like, Well, that's fine, but like, you know, we should go down this path instead.
But I guess if I was working like, you know, if, if I was like a Linux kernel maintainer or something, it probably is more useful to know that like, yeah, five years ago in like the sound card driver in the Linux, you know, core, we had to like, you know, do this. And here's the, here's the blog post length, commit message explaining why.
Chris: Oh yeah. I'm a big fan of the blog post commit message for a one line change. Those are some of my favorites. One thing that I, I will offer here is that the question at the heart of this is, is it worth it? Is it worth the effort to produce this lengthy commit message that captures all of the details versus not doing that?
And my stance is I'm kind of doing it anyway because I'm writing a poll request, and the poll request is gonna have a description. It captures all of this context and is me explaining to my colleagues at this point in time, why are we making this change and why are we making it in exactly this way? What else might we have considered?
What was the reason? Like, what thing happened that caused us to have to make this bug fix? And then what did we run into that didn't work the way that we expected? And so I'm almost always writing that anyway. And so I've adopted the practice of I will work on something in a feature branch until I get it to the place that I'm ready for review.
I will then locally squash down the commits and write that detailed commit message that captures all of that context. And then when I open the pull request on GitHub, it just happens to inherit it from that commit message. And by virtue of that, I, I sort of get the best of both worlds. So it's already a conversation I wanna have with other people.
I'm just trying to capture that as well for future versions of me that is looking back at the history of the code.
Matt: Yeah, and I, I think it's probably worth. Pointing out that it's a distinction and maybe it's like not a meaningful distinction, but sometimes when people say, like, writing good commit messages, I think they're talking about like literally every git commit that you are making. Versus, and I do something similar of, I don't particularly care about my commit messages when I'm doing development, but like you said, when you get to the stage where you're going to merge it into the, the main branch, like doing a pull request and having a nice writeup in there, I think that seems, similar, but maybe like different, or maybe it's just the advice, like people say like, write, get, write good, git commit messages.
And maybe what they should be saying is, like write good pull request, you know, posts.
Chris: Yeah, I, I think that that distinction is meaningful. I hadn't even considered that it was part of the question, but I write absolute garbage in my work in progress commit messages. Actually, most of the time my commit message is WIP, but I often misspell it because I'm just kind of smacking the keyboard.
I, I commit constantly because I'm like, Oh, this is a checkpoint in a video game. I'm saving my current status. I'm gonna do that all the time. And those are absolute throwaway nonsense. I may write a random word that references like I'm at this step in the process of what I'm trying to build out, but it's, yeah, it's very much a barbell strategy of absolute hot garbage when I'm working on the future branch.
And then when it's time to open the pull request squash down, write something meaningful, capture all the contexts that I have, and that eventually becomes the one commit that gets merged into main, But definitely not along the way. Oh God, no.
Matt: Yeah. And I think that's, that's like where I kind of get hung up on some of this stuff because I, I think I agree almost a hundred percent with that. And so the, the reason that this even kind of got implanted, like Inception style into my brain was there was, this guy David Hemphill, who is in the Laravel, community, and he has this, this tweet that he had sent, which was, basically you only need to gtt commit messages and those are init and WIP. And so there's init, which is the first one where you set up all the like, app stuff, you know, set up your framework. And then everything else is, is, is just WIP. And so he calls this like, a way of life. He sells like a, a merch, like a, there's a hat. I have a hat sitting on my, shelf over here that just says "W I P"...WIP.
So. I like that seems like the most extreme version, right? Of like, this is literally just like the equivalent of hitting the save icon. Like you don't, you don't, you don't, when you're editing a document or something, you don't, you don't name each, each revision. But I think David would also say that like, yeah, if you want to do a pull request, you're gonna combine those all down.
He's maybe a little bit more cavalier and, and that he's like, Well, sometimes it really doesn't matter and if you merge, you know, 20 WIP commits, like, who cares? But I think that's like, the most extreme position. And so that's what I think people sort of react to when you say like, you shouldn't spend any time writing your git commit messages.
I think maybe there's the implicit or hidden, assumption in there, which is sounds like kind of is your process as well of like, that doesn't mean that your pull requests are just like blank pull requests or like the body doesn't just say WIP and then you're, you're, you know, merging it like that,
Chris: Yeah, the, the things that I do on a feature branch, I am allowed to make whatever mess I want. I'm allowed to break the tests. I'm allowed to do anything now, allowed to truly have work in process that doesn't actually work. Those are the rules that I have for myself. But the minute that I, go, the minute that a pull request is getting opened, then stuff has become real, then I need to have code that I am proud of, that I will put in front of my colleagues to get a review.
And I need to be able to tell the story of that with the caveat that occasionally I'll use GitHub's. What do they, do? They call it a WIP PR or,
Matt: Draft PR.
Chris: Draft PR and event like that's a useful tool for, I've not quite achieved that end state, but I want to get feedback on this current thing. And I like that there's that delineation in the pull request world.
But yeah, I get a ton of value be by like spelunking through the history and so I'm willing to work on that, but not in the moment. In the moment. I'm just searching for some truth and I'm gonna WIP commit all day.
Matt: Yeah. The most, the most extreme example I saw this was someone that. Had, written a blog post for something called Commit Driven Development, which was where they would write their commit messages, first and then they would write the tests and then they would write the code. And, I thought it was an interesting exercise, but I couldn't possibly ever do that.
Chris: No, that's a little, yeah, a little too aspirational in my mind.
Matt: Yep. Okay, so there's a couple other things I want to get your opinion on because when I was sort of doing some of my research on like, let me make sure, let me make sure that, the state of the internet is, is still saying the things that I, I think it is. So like I had this, I had this view that, you know, people say that writing good and detailed commit messages is like virtuous and a best practice and something that is worth, worth doing.
And I. So I found this list, which is the seven rules of a great git commit message. And I think this is just a list that keeps getting recycled. I didn't track down the origins, but it seems like, maybe, maybe, Linus was somehow involved in making these rules. I just thought it was kind of, interesting to look at them now because I don't think they all even like, matter or make sense.
And, some of them are the most, like what is in, in, in typical like software practice thing. Like they're just like pedantic for the sake of pendatry, I think. So the seven rules, I've got 'em here. Number one, separate the subject from the body with a blank line. So yeah, you need to put a subject and then a blank line before the rest of your commit message like this to me, like seems like has almost no value other than like, it looks, looks nice, I guess. But...
Chris: Is that not required for git's parsing? I mean, I guess are they just gonna take the first line regardless? And so this, the blank line means nothing,
Matt: I believe so, or like in the log summary, maybe it will take the first line. But I thought it was just, like it struck me that this was the number one rule of the first, you know, the first rule of the seven rules is about, you know, formatting, of lines.
Chris: Well, you start at the top.
Matt: yeah, I guess I, maybe you should, you know, work your way down.
The second rule, of course, is limit the subject line to 50 characters, which I'm sure is some, you know, limitation of, you know, the, the width of a terminal from some computer built in the 1960s. Then we have capitalized the subject line. I guess that makes sense to me, but again, it's like this, this is one of the rules.
This is rule number three, that the, the third most important rule of a great commit message is that you've capitalized, okay? Do not end the subject line with a period
Chris: I mean, that's just pragmatic cuz you've only got 50 characters. So why would you waste one on a period
Matt: Yep. And then, then we get to the, the grammar section where we have used the imperative mood in the subject line. I'll be honest, I'm terrible at grammar.
I don't know if I could even give you a good definition of what the imperative mood, would be. I'm assuming that's like, you need to say summarize changes and not, you know, like summarized changes
Chris: I think it's like,
Matt: a tense, past tense versus,
Chris: Changes rather than changed. So this commit changes the blah, blah, blah. And it's meant to be like, this is what this patch does. If applied, that is the way I've heard it. And it has to do, I think like you're saying of like, when Linus came down from on high and handed us git, it was meant to be for email-based patch sharing for the Linux kernel. And yeah, these, these don't feel super useful to me. I'll say that.
Matt: Yeah, that's, that's how I had had it explained to me in the past was, was, when you say like this commit when applied, we'll do this thing so you shouldn't use like, the past tense of things because that implies that it has already been done and yeah. Seems a little silly to me. And then, you know, number six, wrap the body at 72 characters.
So just a different arbitrary, number 72. Not, not to be confused with like isn't, I feel like 80 characters is like another
Chris: I think 80 is pretty
Matt: based one.
Chris: Yeah. So I don't know why that
Matt: Yeah.
So then we get down to number seven, which is use the body to explain the what and why versus the how, which I think is probably the only rule on here that I think, really even makes sense.
Chris: Yeah. I, That one feels useful. The thing that's interesting is you end up with these, like, I I, I actually just click through to the blog post now that describes these, and in the blog post, there is the why of these rules. But sort of critically, the rules are the how. So they, they almost contradict rule seven.
And not that they're meant to be a git commit message, but I think that's the critical thing with all of these is like, one must write good git commit messages. And it's like, well, why though? Like, what does it matter? And my answer would be, well actually, I often go back and look at the git commit message to try and understand the reasoning behind a change.
So there's utility there, there's a tradeoff. You have to do some work. Is it worth it? That's a question. But you have to anchor to the why of the thing. Instead of just saying, one must do TDD and one must do good, get commit messages. It's like, Yeah, but like, but why though? What's the benefit? Let's make sure that we're clear on the benefit and then let's make sure that that benefit remains true over time.
Because also the software industry changes every 12 minutes. And so what used to be a best practice can easily fall out of fashion or no longer be relevant.
Matt: Yeah. And I
Chris: to the why of the thing, then it's.
Matt: yeah, cuz I think we sort of stumbled on an example of like how, you know, the industry has changed and some of these don't even make sense just when we talked about like a pull request versus commit messages. Because I think you could probably apply these rules to your poll request and they maybe make a little bit, well, I don't know if these rules still make any more sense, but like, you don't need to worry about separating the body, you know, from the subject with a blank line because they're two separate fields in like the GitHub ui and you don't need to worry about wrapping, characters because it's rendered on a webpage.
So it will, you know, wrap on its own instead of in a terminal.
Chris: This is one since we're, we're in a pedantic space, which is often a space that I find myself in. But you know, we're web developers, so there we go. That's gonna be the name of the game. Why did GitHub decide to maintain line wraps? It's like fundamentally against the markdown standard. And so they parse the description as markdown, but they maintain the line wrap.
So occasionally I'll have a line, like I'll have a bunch of lines that are at 72, cuz that's what my editor tells me to do, and I've just kind of normalized that. Then occasionally I'll like copy and paste something in, and suddenly that's hugely long. And I'm like, Why? Why did you make that choice though?
And now everybody else is like, Oh, we use GitHub flavored markdown. I'm like, Oh, please don't,
please just do the markdown thing of flow the lines together like html.
Matt: yeah, I don't know. I don't know why that is. And maybe someone can Splunk through 15 years of commit history to find, the answer for you. But I suspect to not.
Chris: Yeah. That, that commit message is lost in the long, long, long ago of GitHub slash GitHub, that repository. Yeah.
Matt: Yeah. I don't know, like the poll requests, have been getting better, but it still doesn't seem to be all the way there. Like I, they've added more features around like squash and merge and, things like that where they can combine, I think they can make like the title of the poll request, the title of the, like squashed commit.
Now there's a setting for that maybe, but I'm still unsure. I don't believe there's currently a way to make a, to make one of these nicer commit messages where the title of the poll request is the subject and then the, the, you know, the body of the poll request, like the, the top level comment is automatically put in there.
That I think would be interesting cuz then it sort of completely, solves the problem at least that I have of like, being messy locally and then wanting to write a nicer pull request, but then being like, Well now am I gonna like copy paste this into the little tiny text box? Like, can't you just, do that for me?
Chris: Yep. It, these, these little workflows that we get ourselves into. I have the dream of the, I've still not quite made the merge queue work for me, but I want like aase based merge queue type thing such that we're always testing on the branch. Never. Like I don't wanna have to test on Maine cuz I've already tested it on the branch.
That's my belief. I wanna, I wanna do that. And then once it goes into Maine, it just gets deployed. That's the dream. But I don't live in that world yet and there's no setting on any CI that I've ever seen that says, Hey, if you've already tested this commit, don't test it again. It's the same you can tell cuz Git knows Get is very good at knowing that question.
Just trust get, but nope, nobody has that setting.
Matt: Well, you know that, you know, GitHub actions are charged per hour, so, Business incentives are not aligned there. I'll just say
Chris: I do know that, I mean, Circle CI has canceled redundant builds, which I appreciate. So they, you know, they could, I'm happy to pay 'em a bunch of money otherwise, but,
Matt: Yeah. Chris, what do you know about conventional commits?
Chris: I've heard the name. I feel like it's, is it in the,
Matt: it's a specification for lightweight conventions on top of commit messages to provide an easy set of rules for creating an explicit commit history and write automated tools on top of,
Chris: is this the one that has like fixed chore, et cetera, like your prefix? I've used it on one project, which was more of a library. It was like a component library system that was being used in a broader team architecture, and it had a little bit of utility there because it made it a little bit easier to generate the change log.
But overall, I found it to be, Burdensome, and that's sort of like semi automation on top of loosely formatted plain text is always gonna be tricky. So I've never had it work well for me and thus I'm, I I wouldn't reach for it. But I also don't work that much in library code. If I found myself constantly in library code and spending a lot of time manually putting together a change log, I might be more interested in it.
Matt: Yeah, that's, to me, I think the, the crux is like, if you need to generate a detailed listing of like, everything that happened between releases, like this is probably something useful. And if not, then it is like probably a distraction. I guess it just depends on like how strict you're gonna be. Like, I'm looking here at the conventional commits project and they're basically trying to be like the semantic versioning, but of commit messages.
And there's like Lins that you can apply to, you know, reject your commits if they don't. The right formatting. There's very, very detailed, specification about, you know, you can say that this is a, this is a feature commit, but you can add a exclamation mark to like signal that it's a breaking change.
And you can scope that this is a feature related to this. You know, like you can say feature parentheses, api and then, you know, bang to say that this is a breaking change on the a, the api. I, I kind of agree with you that I think it is probably, not important unless you're generating a change log.
And if you are having to generate a change law, it's probably, it's probably helpful. The thing for me is like, kind of just like, if we step back a little bit and talk more about the industry as a whole, like I find that stuff like this is, very difficult for people, especially newer people to, Encounter and then know when and when not to use because I, I look at this website, it's like conventional commits.
It's got a very nice website, you know, conventional commits version 1.0. It's, playing off, you know, seber, which people say is so important. And as we've kind of discussed, it's like if you're not writing a library and you're not generating change logs, I don't think this is that important. But if you're sort of new to programming or like you're, I'll say like, you're drawn to like the craft aspects of this.
You say like, Oh, this looks good. I should be doing this, and, I should form like value judgments on like, you know, code bases that don't do this are, you know, worse than code bases that do do.
Chris: Yeah, I, I think what you highlighted at the beginning of that, of when you are newer to this industry, it's so hard to differentiate the, the useful things that we have from the less useful things. I mean by, by the nature of what we do, we are sort of makers. We have the ability to produce new things that are useful.
We can build our own tools and. I, I think it's probably fair to say that it is sort of in the nature of a developer to want to do that, to want to automate where we see any sort of repetitive tasks. And so we end up with tons of automation. We also, we like to introduce taxonomies and, and ways to look at the world and sort of fit it into boxes.
Cuz again, that's kind of our job. We have to get into arguments with computers and trick them to do our bidding. And so we have to be wildly specific in doing that. And thus I think it all leads us to like, maybe we, maybe we build too much automation and maybe we try and over constrain things. In some cases, the amount of times that thought pot that we had a lunchtime conversation about whether or not a hot dog is a sandwich.
And the cube rule of food is so, so many times. Just so many times. And I. Honing that, that desire, that intention as a developer to like, one are the times that I actually should be doing automation versus not. One, are the times that, like, what is the utility that this tool set framework workflow, et cetera, brings.
I think that's, that to me is actually a good measure of like, are you approaching senior developer? Are you getting further along in your career? Is the ability to determine which of these are useful, which are the things that are worth investing time and, you know, experience, budget into versus what is not, what is, you know, more noise than anything else.
Matt: Yeah, I mean, I think I, I have an opinion and I'll, I'll, I, if, if I'm charitable to myself, I can say it's being pragmatic. And I think that it is, like, it is probably harmful to give the advice of like, you should be writing detailed and like, good commit messages to newer developers. Because I just think it's like so far down the list of, things you should be working on and improving that, it's like, it doesn't, it never hits that like ROI for me.
It's like if you have, if you have time to like be, getting better at this, then like you're already probably. Like, you're probably good. Like you, you know, it's like a luxury. In some ways I think that was kind of my main response initially when I had, when I had said that I think, you know, detailed commit messages are, you know, mostly pointless.
And people said like, we can kind of walk down the tree, you know, the, the dialect tree of like, well, yes, they're good at, helping in history. And I've had times when this has been helpful and, and I agree with that. But I think my overall message was like, if I were to rank, their usefulness, it was like I, I, I feel like clear code is, the most useful.
And then after that would be like a test, that, that explained, you know, some reason for the change. Right. And then below that would be maybe a code comment. And then the last thing, on that list for me would be a commit message. So, With that ranking system, I would say, like I would, I would much rather people spend time getting better at, like, writing clear code or writing tests, or even writing a code comment versus, writing a commit message.
I don't know. Would, would you take issue with that?
Chris: Issue is a strong word. I would, So like the first two, I a hundred percent agree with that. And the specific ordering. So like clear code is the most important thing. Code's what matters. Tests are super duper important and valuable. So I would put them next on the list. And they are way, way, way up higher.
Like they are a different category of importance. And then the other two that you listed are, you know, somewhere at a. I personally try and avoid comments wherever I can or that, I mean, this is a whole other, bike shedding diatribe that we can go on. I have seen precious few, maybe none comments that I've been like, yeah, that, that warrant that was warranted.
And I've seen plenty of times where there was a comment that was just an outright lie that had gone out of sync with the associated code that it was attempting to comment on. And it's like, one plus one is two of course, and then below that it's doing multiplication. It's like, it's not even addition anymore.
Like, what are we doing here? So I personally lean towards commit messages. Granted again, not like in the moment, but
Matt: in like a commit message doesn't suffer from that issue of getting stale because it is tied to the change. Is that, So I guess commit messages have the issue of, I don't know what a fancy way of saying this. There's like a temporal aspect to it, right? It's like it's attached to the thing, but changes in the future may have changed how the code works.
Whereas a code comment is, It's not attached to the, to the change, I guess, Would that be the, the, big, the big reason why, you would prefer one or the other?
Chris: Yeah. It's not attached to the moment in time where you're making that change. There's also, actually more often the way that I will do this is instead of a code comment, I will extract a method or a variable that is named for essentially what that comment is. But now it's actually a part of the code rather than text that is adjacent to the code.
And I find it's much harder to just misuse a method that has the name that clearly says, like, This method adds one to the thing. It's like, if that's in a comment, it's easy to ignore, but if it's in the method name, you're probably gonna
Matt: So you would, you would have, you would have a method that says something like, you know, add additional timeout for, you know, Twitter API rate limit flakiness or something, instead of, writing that as a code comment above.
Chris: Yes. Yeah, that's actually a really great example. I was struggling to find a good example, but that is exactly the sort of thing that I would do.
Matt: Yeah, I think for me, like, I, I think I agree with you on like, number one, clear code and number two, test being like above. The thing that I've found in practice is like the distance, the distance, like away from the code, has mattered more to me than like the, the chance that it could get out of date.
So the fact that the code comment is right there in the same file as the code versus the commit message or, you know, and we've been using sort of commit message and pull requests somewhat interchangeably, those being in a different system, it's always kind of the same issue I've had with like referencing like a Jira ticket in, a commit message, right?
It's like, yeah, that's probably the better place for it. But the fact that it's like one hop away means that it just, it's less likely that someone will follow that link and then. Open that up.
Chris: Yeah, I think that's true. Again, my, my stance is you build up all this context when you're working on a feature, and so why not capture that and. If you frame it as like, should junior developers be focusing on writing good commit messages? No, and certainly not to the, like, it must be 50 characters followed by line break, followed by 72 characters wrapped in this way.
Like, that's not the meaningful stuff. The meaningful stuff to me is you have a bunch of context in your head as you worked on this feature, write it down, tell me a little bit of a story about why you did it that way and with a focus on the point in time where you're communicating that to your team, which for me is the poll request or the code review.
And so I, I definitely wanna capture that context. And if you, if you don't treat the poll request as a different thing, if you treat it as a view on the commit, then it tends to be pretty easy to like hold onto that. But, agreed that it's not something that I would push super hard on, or especially if someone were newer to the team and they were trying to get ramped up on everything.
I'd be like, that's fine. That commit message says some stuff. I'm not super worried about it. It works and that's what matters. You wrote a test, really happy about that. I would definitely focus on those elements significantly more.
Matt: Yeah. All right. My more spicy takes here on this. I think most software developers are, not good at writing. And so by saying that there's a practice that requires, good writing, I think that's kind of a baked in assumption to this. Cuz you could have a long detailed commit message, but if it is like, not well written, then it's probably even worse than if there was, no commit message.
Like I'm imagining trying to read through like, you know, a five page, commit message where it's unclear, and kind of ramly, like, is that actually better or is that giving you a false sense of there is information here that I must, must. So if people are bad at writing, why are we encouraging or saying that like, this is so important.
If, if, if, then we expect that a lot of people will not actually be able to like achieve the result.
Chris: Yeah, that is spicy. It's a, it's a much hotter take. There is probably some truthfulness to what you're saying. I, I will say that I have had the great fortune to work, primarily at thought bot with some really talented folks who use the, the word writing. But I think communication is probably the, the more generic form communication and perhaps empathy.
And like, if you wanna mix those two together, I'm starting to blend or blur the edges, but, The ability to put yourself in someone else's shoes and communicate to them, you know, something that is true. I actually think as a core aspect of being a software developer, my job is to talk to some humans, get some words that they're saying, and then go trick a computer into doing that thing that I captured from a conversation over here.
And so I think communication is actually a pretty critical skill and one that perhaps is under-emphasized. I think there's a lot more focus on sort of like technical chops of like, Oh, can you work with the React context API and deal with the hooks arguments and whatnot. And, and a lot of, do you know how to do system optimization and all of that.
And I'm honestly significantly more interested in can you talk to humans and then take the problem that they've described and get the system that we use code to maintain, get it to do the thing that we need to do in order to. And the amount of, translation that needs to happen. There is a really interesting one.
But again, I, I've been very lucky, at Thought Bot and then also at Sage, well, very much carrying on, carrying on in the thought bot ethos of communication is a critically important skill for developers. And so we bias towards that and thus writing sort of naturally falls out of that. And so, yeah, I want those people to tell me a story in a commit message, Folks who are not great at communication.
No, I don't want a five paragraph essay about the big o notation optimization that happened like that is less useful to me. I wanna, I, I wanna hear the story of how this solved the problem that we had, or critically the problem that our users had. That's, you know, the most important end of the whole conversation.
Matt: Yeah, I think, in, yeah, in my experience, if you're working with developers either on your team or on other teams or, other projects and like, they're not good at communicating, it's like their code is not gonna be good at communicating. So I don't know why we would expect someone to be able to like in pro, you know, like be, so much better.
So that's, that's where I think it kind of gets back to my hierarchy there of like, if, if you're not good at writing clear code, like the last thing you should be worried about is like the commit message for the code. Like you should focus on, on that, and that's where you should be spending your.
Chris: Matt's hierarchy of what we should focus on.
Matt: I guess.
Chris: Yeah, I a hundred percent agreed. I just, I. Again, have been lucky to work in the space where yes, we are communicating well within the code and then we'll go another step further, but it's not a given. And it is, it is definitely an uphill battle. And honestly, I, I struggle with it sometimes because when I'm, when you're in the code, when you're working with a compiler or with the interpreter or whatever it, like, when you're at that level, it's just this very different thing.
And then trying to sort of bounce back and forth between the domain language and the humans on the far side of this code and the computer at the other end. Like it's actually, I think, quite a difficult job that we have to balance that, that middle space. And there are folks that are more biased on one end or the other of that spectrum.
But I think, fantastically talented developer really can bridge that gap. Well, and I think that's one of the things that makes them stand out as great developers.
Matt: On the flip side of, most people being bad at communicating, I've heard, and it is must be true because there's, you know, a prolong standing acronym in the programming community for, Rtfm read the f-ing manual.
Nobody reads anything. You have developers that won't read, you know, your, your story or your, your ticket in Jira. You have people that won't read the instructions, of a library or read the documentation. If, if we don't expect people to read anything, why are we writing these commit messages?
Chris: Again, I think a spicy and excellent take. Is it a trope? Is rtfm a trope? Like, is that a real thing? I like, I, I've certainly, I don't know that I've said it. I, I hope I've been kinder in the moment, but I think it's the sort of thing that is a response to someone who isn't aware that that information is out there and available.
Like, it's a way of saying the question that you're asking is actually more obvious than you think. Go ask the place that we ask questions. Don't bother a human with it. But. I certainly read, I've read a lot of documentation in my life, and I think good documentation often, is a differentiating factor in terms of framework success and that sort of thing.
Like how collectively, how much stack overflow have we all read? Well, maybe just copied and pasted from, So maybe that's a bad example, but, people read, developers read.
Matt: You're more optimistic than me. I think
Chris: I've been lucky to work with great people and I haven't had to build huge teams.
And so I'm, I'm somewhat biased towards the stuff that I do and I'm interested in.
Matt: Yeah, I guess like. I just see this bigger trend in the world that like no one is reading, long, detailed things anymore. Right? There's like people, I mean, and we talked about it at the, the start, like, you know, Twitter is not the place for a long, in depth, discussion necessarily. You know, instead of writing detailed commit messages, like should we be, recording a TikTok about, this feature and, you know, doing, doing something like that, leaning into the, the short attention span of, the, the next generation.
Chris: I mean, you say the next generation, but like my attention span's broken too. And I have done something like, I would say 50% of the poll requests I put up, have a screenshot on them, Another 10% have a loom or screen recording of some sort. So like, in a way I, it's not TikTok, but, Cause I don't know how to use tech.
I'm an old, but, but I do do video recordings for that. And I also a big block of text that's never gonna work. People don't read that. It gets boring. If I bold some words, if I make a list, if I have headings, if I break it into sections, it's more scannable. And then like that is something that I do. I do that in my own like journal entries because even me reading my own writing about my own thoughts from the past that I thought I had to write down cuz they were important, I'm still gonna scan over those.
But if I've structured it in such a way, you know, again, capitalize on the context that you have in the moment and be as kind to the future reader as possible. Because maybe their brains have been, scrambled a little bit by the TikTok age.
Matt: Yeah, I think it, it is interesting and I think, I would agree that it's probably, it, it's, it's probably fair to say that there are more ways than just written texts to communicate changes, especially in software. I guess on the other hand, I think, well, that then sort of, goes against some of the purported benefit of writing commit messages and that I don't think, it's as durable to like scan through, that sort of thing.
Right. I guess you could like put the, the, you know, the URL of the Loom video in a commit message. But you know, are you still paying for the, the Loom account? Has that video expired?
Chris: Oh, this is super easy. You just base 64 and code that video and you put the entire binary object right in there. It's great.
Matt: I think they invented, I, think they invented this already and it's called the blockchain.
Chris: I mean, Kit is a blockchain at the end of the day,
just to be
Matt: what I've
been told.
Chris: it's the only one I like. But yeah,
Matt: Yeah. Okay. Are you ready for, do you ever watch that show where they have the hot, the hot wings?
Chris: Oh yeah, hot ones. It's great.
Matt: And they get progressively hotter and spicier.
Chris: Uhhuh , Are we about to go to de bomb?
Matt: Yeah, I don't, Is that the last one?
Chris: I think so. Although there might be one other and then they do the last dab or something like that. But I'm, I'm ready for the spiciest of takes.
Matt: My spst take is that, commit messages, as a best practice have been, encouraged and propagated by consulting companies whose primary job is, the primary deliverable is, is the, like experience of software, software as a craft. And what they're delivering is a nicely bundled piece of code with, you know, great unit test coverage and, you know, high quality, you know, commit messages.
Whereas, A bigger percentage of people actually working in software are working for businesses where the outcome is, really divorced from the actual, piece of code. So this is a, this is ayop to help convince business people, of their high rates for the value that they have produced, that, that this must be better.
Chris: , there's definitely truth in, in what you said there, that sometimes there's the, the optics, the, the look of it.
What are the, the tangible things that we can point to that are the practices that an agency might bring. But at the end of the day, you know, does that get you repeat business? No. Because there's not actually a ton of value in those sort of things. It's actually interesting on some of my most preferred client engagements, I wrote very little code and like my work was in talking to people about how to talk about software.
And again, coming back to that idea of communication being so much a part of the work that we do. But yeah. Is this, is this just a thing that we say we do so that we can have a thing that we say that we
Matt: It, it almost reminds me of, when you have like a product comparison page and they have all the check boxes of, you know, features that your app has and the other one doesn't have. And as you go further down the list, you're just like making up, things where you can like, put the check on your side, right?
It's like, you know, oh, you're developers, you know, they're not writing detailed commit messages, like, we will write detailed commit messages. Or, you know, this, this agency is charging, you know, a much higher rate. So what is, what is, a practice that they do? And, this seems like one that is, easy to differentiate without any actual, better outcomes.
Chris: Yeah, I mean, I, I think a version of what you're describing that is very real is Scrum. Like I have, battled against Scrum in many client engagements because I believe that is a lot of ceremony with, with no real utility. The other thing that's interesting is like, as we're digging into this conversation further and further and it's, it's clear that this is a thing that you're like, I don't really believe in this and this seems like a waste of time.
I personally have never questioned it. Like this has never been painful, such that I'm like, Man, is this even worth it? Tests, I will say, is something that I've questioned at various points or TDD more generally, although I won't say that I actually practice t DD all the time or anything like that. I do it sometimes because there are times where I think it's a great fit, but testing in general is really hard and takes a bunch of time.
And there are times where I look at it, I'm like, Is this test even valuable? Is this doing the thing that I need it to do? Whereas writing that commit message is, So it, it's not terribly hard in the moment for me because I have that context and the idea of like, I'm a digital pack rat is a thing that I often say about myself and like when I have this context, the idea of just letting it kind of fade away feels so wasteful to me.
So I'll take frankly what represents a couple of minutes to draft that poll request description, that commit message. You know, we're, we're conflating those two, or I'm conflating those two ideas, but there's. So much utility there and so little costs that it's never even been a consideration of mine. So this is one that definitively is useful, but the category of things that you're describing where it's like, are these things that we only do so that we have stuff that we can point at that are ceremonies, rituals, obvious observable behaviors that look like fancy software development?
The software craftsmanship movement is a really interesting one that I'm both really intrigued by a lot of it. And then also not pair programming is an interesting trade off. I absolutely love pair programming, but I can see people looking at that and being like, That seems like a waste of time. And I'm happy to defend that one till the cows come home.
But it is one that I can see this sort of conversation happening around, and there's so many of them. But like, yeah, a good commit message costs me very little, especially because most of my com, 90% of my commit messages are whip incorrectly spelled with no other words.
Matt: Yeah, so I guess if the cost, like as the cost to purchase zero, then the benefit doesn't need to be high for positive roi.
Chris: That expected value equation rules everything around me.
Matt: Yeah, that, Don't get me started. If you ever, if you ever want to get into a good debate with somebody about expected value, just ask them if they would play Russian roulette.
Chris: I mean, how much, How much money is on the table? Like I would never play it, but,
Matt: Well, the expected value is positive, so you're not a rational actor obviously.
Chris: Oh no. It really depends on how much I value that money. the act. Okay, Nevermind. We actually you accidentally. Nerds sniped me with Russian roulette, which is an aggressive nerds snipe to be clear. But yeah,
Matt: Yes. Yep. All right. Well, we've been chatting for a bit. I'd like to ask you detailed commit messages. Do we need them?
Chris: Yes. That's my stance.
Matt: you've got Chris's answer. My answer is no, we do not need them.
Show notes, links and a full transcript can be found at yangni.fm -- today's guest was Chris Toomey, CTO at Sagewell financial .
You can find Chris on Twitter at Chris Toomey. And I'm your host, Matt Swanson. And you can find me on Twitter at underscore Swanson.
Until next time, just remember you. Ain't gonna need