Skip to content
489: What makes a codebase welcoming episode artwork

Jan 13, 2026 39 min

489: What makes a codebase welcoming

from The Bike Shed Hosted by thoughtbot

Joël and Sally tidy up the place as they discuss the different ways a new codebase and team can feel welcoming to them. Together they break down the things that help them ingrate into a new project more easily, explain why the lore of a project can be sacred to some, what you can do in the present to make things easier for a developer down the road, and why communication is crucial for keeping everyone on the same page even long after you’ve moved on. — Check out these resources for a deeper dive into some of the topics mentioned in this week’s episode - Fixtures - Hierarchy of Documentation - Domain Modelling 1 - Domain Modelling 2 Thanks to our sponsor for this episode Scout Monitoring. Your hosts for this episode have been thoughtbot’s own Joël Quenneville and Sally Hall. If you would like to support the show, head over to our GitHub page, or check out our website. Got a question or comment about the show? Why not write to our hosts: [email protected] This has been a thoughtbot podcast. Stay up to date by following us on social media - YouTube - LinkedIn - Mastodon - BlueSky © 2026 thoughtbot, inc.

Episode details come from the podcast's RSS feed.

Embed this episode

Ready to play

489: What makes a codebase welcoming

0:00 39:13
of matches

Transcript Auto-generated, may contain errors

Have you ever tried to debug an issue in production while switching between your error tracker, log viewer, and APM tool? Maybe you know how painful it is when you can see the error but can't find the relevant logs, or when you see slow performance but it can't connect to the root cause. Scout monitoring is all in one platform, built to make your life easier. With log management, performance tracking, and error monitoring coming soon, all of your data will be together at last. You'll go from bug to fix in one place. The result? Less context switching, faster debugging, and monitoring that actually helps

you ship code instead of distracting from it. No DevOps team? No problem. Scout works with your existing stack and gives you insights in five minutes, not hours. From bug to fix in one place at ScoutAPM.com.

Hello, and welcome to another episode of the Bike Shed, a weekly podcast from your friends at ThoughtBog about developing great software. I'm Sally Hall. And I'm Joel Kenville. And together, we're here to hear a bit of what we've learned along the way. So Joel, what's new in your world?

I recently did a project where I wanted to get a better sense of the coded hand, and the way I ended up doing it because it was sort of spread across a lot of different files. It was one of those like service objects, calls another service object, calls another one in a like, fractal pattern. I was struggling to keep track of everything. And so I started drawing out a call graph as a diagram to help me better understand things. So like a tree or a graph diagram just sort of like this thing, and then like a call B thing, those call these things in that way. Cool.

It did. One of the things that's interesting though is that as I'm diagramming the file, there's a certain amount of ambiguity in terms of like how they should be diagrammed. I think we all intuitive have a sense of what a call graph is like. And then in a language like Ruby, you get a situation where you've got some sort of root method that's like where you're starting your graph from. And let's say it has a method chain inside of it. So in its body, it has A dot B dot

C dot D. Okay. Like how would you graph that out? Is that a chain of like A points to B points to C points to D? Like, you know, great, great grandchildren of the root function? Are they all

siblings, children of the root function? How do you think about something like that? Yeah, it's interesting. I would say that they're all siblings and children of the root function because you're chaining them sort of as just a convenient way to say I'm going to call this one, and then this one, and then this one. But you could just as, you could, it would be equivalent to call one and then take the result of that and call the next one. So like function A is an

actually calling function B. You're just calling function B after you, the result of function A, right? Well, you're calling it on the result. I don't know if that makes a different, right? A function chain or a method chain rather than like a pure functional composition sort of thing.

Yeah, it's interesting. What did you end up deciding? I ended up deciding the way that you were saying, and there's a couple of heuristics I was going with. One of them was the idea of lexical scope. And so knowing the things that are in the body of the function, anything has a reference in the body of the function should be a direct child of it. Another one is looking at a call stack. So if

an exception were to occur in any of these methods, what would the stack trace look like? And you don't see if the last one of the chain or method D raises an error, then you don't see a stack trace, it includes CBA. You just see directly root function, to call this and it blew up. That's because each of the others in the chain returns control backup to the parent. Yeah, yep, that makes sense. Some of this

got me into some pretty academic contexts. I was trying to see is there any prior art, you know, purely other people thought about what a call graph is, and here I am sort of running into ambiguity. How should I do this? And pretty soon I'm stumbling into the idea of context sensitive versus context insensitive call graphs, which are also really interesting. The idea of should every method or function have a single node in your graph or all the different ways that they could be called that might result in different outputs have their own separate node. So for example,

you have a function and it has a conditional in it, and it might call some other methods in one branch and a different set of methods in a different branch. Well, now that means that the children of that function, depending on the argument you pass in, are going to be totally different. That the context sensitive is one. So now you say when method is passed, and even number versus when method is passed in odd number, they each get their own node on the graph. I managed drawing that out very quickly lead to a bunch of ideas for refactoring and cleanup. Yeah, yeah. In my case, it was too complicated,

I just went to the context in sensitive one where I was like, you know what, I don't care that there's like conditional branches and everything, children of a node are just all the possible things that might call and we'll leave it at that. Okay. Yeah. Yeah. Otherwise, I'll tell the graph just because we're really, really quick. Yeah. There are also static

graphs which you get from analyzing the code sort of at rest, which is what I was doing just sort of looking at it, or you know, if you're getting fancy with a parser or something like that, versus dynamic ones which you can generate by actually running the code. Oh, interesting. I think maybe analyzing the call stack or something. And I imagine there are tools for generating those. Yeah.

Yeah. Yeah. Yeah. I could, I'm gonna have to talk about this more in depth at some point because it sounds very interesting to me. So I feel like there are a couple of scenarios I can imagine here in my head for if I had, you know, I was trying to understand a new code base and using this tool, one of which would be, you know, I had some assumptions about things that I thought were not ideal going into it that I was confused about. And while creating the call graph,

end up realizing like, oh, that actually does make a lot of sense and that does seem like the right way to do it. Or the other way around discovering things that like on the surface seemed perfectly reasonable, but as you dig into them and draw them out, you start to doubt the data that you I think I've used this for a few different purposes. Sometimes it is for explored for like, wow, the thing that I thought was just going to be like a service object is now a whole like tree and I'm a little bit lost. Give me a map. Just a high level overview. So then I can know easily,

oh, I need to jump into this file. That's like a great grandchild and not like jump, jump, jump. And now I've got 20 tabs open up in my editor. Yeah. Sometimes it's also, I know an entry point.

I know that we hit a particular controller action and that's what triggers some behavior that I'm not quite sure. But I don't know sort of how I get from that point to maybe another known point where maybe there's a bug or I just know somehow I think this other object is triggered, but I don't know how it gets from the entry point to that. And so then tracing it out can show me that path like, oh, we call it through this thing because this other thing is a conditional and sometimes when these conditions are true, this object is called that kind of thing. Cool. That seems very useful and like a kind of thing where I could just go down a rabbit hole and spend a whole day.

That is absolutely what I ended up doing. This is a situation where I've been a little bit of bike shedding, right? There's a, it's probably for these purposes, find and not having the exact specification of how you want to do your graph, right? Really, you just want to know like there are nodes you can trace code through and an approximation is fine. But I've done this enough times where I've been like, oh, I don't know what to do in this situation or what to do in this situation that I took some time to dig into things a little bit more. And it was really enlightening. I felt like I

learned a lot and it got me to maybe think a little bit more about code execution in general. Yeah. Cool. I guess I've been going down quite a rabbit hole there. What is new in your world?

Well, I am in the last week of this project that I've been working on for months and months and months, the one where I've been, you know, experimenting with react and typescript and things like that. And it's always like kind of a bittersweet leaving a project, a client project because often, you know, there are a variety of reasons and engagement would end, many of them, which is natural ends, which is what this is. But it's not like the product is totally done. So we haven't wrapped something up with a bow. And like, and now this is an excellent product and it's done. It's more

like, and now we've achieved the sub project goals that were part of this engagement. So we're done. So there's, you know, the part of me that's like, oh, but I kind of was interested in doing this other part and I'm curious to know how that will turn out and just sort of like, you know, accepting that they were loose ends that I'm never going to see tied up there. It's always interesting. Even when it's a project that maybe at the beginning, I was anxious to not be on anymore, which I will admit there were moments in this project where I did not want to be involved anymore because I just was tired of the react. Yeah, but now I'm kind of like, oh, well, I kind of felt like I had really

gotten into the rhythm of things and understood how this stuff is working together. And like, I'm wrapping up the last bit of like a major feature, which feels good. But just that part in the consulting lifecycle where you have to say goodbye to one project and then get excited about ramping up onto another one. So that's interesting. Yeah, I feel like some of those trade offs are inherent to working in a startup, right? The

constant having to say, look, there's all these things we'd like to do, but we've got limited resources. What can we do that we'll fit out of the scope of what we want to do that sometimes you get a heartbreak of cutting scope or saying we're going to deprioritize features. This happens in the product level and at the code level. But I feel like it's consultants. We have that sort of almost like at a take all of those feelings and then ratcheting up the notch. And then adding the

people feelings. Yeah. You know, because I've been working with these people for, I don't know, I think eight months at this point, and they're great developers and kind people and it's like, oh, I'll miss working with this team every day. But it's all inherent to consulting. And part of what I like about it too is that I'm excited that now I get to work on a new problem. But I'm always

a little bit haunted by the things I wanted to do that I didn't get a chance to do, you know? Yeah, that road not taken. Yeah, yeah. What could have been sort of a sliding door is for with code. So I guess that means you're going to be onboarding onto a new project soon. And as a consultant,

like part of our skills is we have to be good onboarding pretty quickly. Yep. I feel like not every project is as easy to onboard as others. Right? There's a pretty wide range. Yeah. What do you think

are things that make a project easy to onboard? Or maybe even the stuff beyond that? What are things that you feel make a project welcoming to a new person? Yeah. And I think that's relevant to the end of a project too, because trying to make sure that I walk away from this current project, making it as easy for someone else to onboard to as possible.

But yeah, I think, I mean, a couple of things that you'll kind of obvious off the top, a good read me, right? And like, what does a good read me involve? It depends on the project. I want to at least know what is this and how do I run it locally? Any quirks about, you know, environment variables or third party things that are a little require a little more complicated setup. I love when there's like a contributing file that has team norms or agreed upon ways to

approach things within the code. And so knowing, you know, this team likes to, I mean, just forecast process, right? Yeah, pull request process. Yeah. Or like, yeah, when merging to staging or things like that. So that's like the high level, easy wins to make a project, I think welcoming is,

you know, a good read me and some decent documentation. I set up script always delightful. And then beyond that, I feel like it comes down to sort of getting to know the code base. So it's interesting that you talked about that call graph because I feel like that's a tool that could be used. I think a really ideal, you know, cozy welcoming project isn't going to necessarily require that off the jump, right? A project that follows conventions is always going to be a lot

more welcoming, right? So Rails is very convention over configuration and a project where the team has gone to great lengths to not do things the rails way. And sometimes be frustrating or, you know, whatever stack you're working in knowing that they have adhered to industry standard conventions and doing things the way the language is sort of intended to be used or some things that are helpful, I think. Yeah, I've been in projects where they'll go like really heavy on a particular pattern that is non-standard. And that can be sometimes a little bit bewildering to sort of find your feet. So like all in, like I said, the dry suite of gems. And that's just a totally

different way than Rails classic. And then good test suite, right? I think that, you know, an ideal beautiful test suite would be something that you could read through almost as like a human story of what the app is supposed to do, especially system tests. Because, you know, looking at the code gets you so far and without really digging through and following the path of like this calls this and then this happens, it's hard to get a big picture view. But I think if there are good tests, both integration and unit tests, they can be pretty easy to jump from a modular class to the test and realize like, okay, this is how this is meant to be used. This is the goal of this.

These are the strange edge cases and sort of get a high level sense of what is happening in there pretty quickly. I guess from that perspective, I might argue that it's helpful to write tests that are sort of contained. So none of this like deep context nesting lets in before blocks and lets it override lets because that makes it harder for someone who's new to just look at an individual test and understand what's going on. Yeah, absolutely. I use RSpec the most and I think that, you know, using this sort of like describe and it blocks and things like that correctly leads to like sentence outputs that will combine together to describe exactly what is happening. Right, like if

you're running it in documentation format or something like that. Yeah, yeah. What about you? What makes you feel welcome and at home in a code base? I think it's one of the things that you said the ability to easily get the project set up, good documentation around and set up. I guess there's

some team dynamic things where just like team dynamic adjacent things where there are processes for things like do we have a process for handling shared credentials, passwords, things like that? Or do I have to like ping the CEO and then wait a day for him to slack me a password which you know, in a smaller startup sometimes that's the way it is, right? So some of these are maybe patterns for just a team that's a little bit more established. Right. All these are patterns that I think once you hire your third, fourth person are probably a good thing to have regardless even at a pretty small size. Something we mentioned on an earlier podcast was the idea of good modularity in your

code or you might talk about code cohesion or maybe sort of the negative example that people sometimes refer to the idea of anemic code. What does that mean? An object oriented context often means sort of a lot of calling code, having a lot of logic in its context, it acts over a raw data structure or an object that has very few methods on it. So having some, I don't know, controller or some other object that just does a lot of manipulation on a hash or maybe even does a lot of operations on some sort of object but that doesn't have a lot of info methods, it's just a bag of data or maybe a few basic methods. And so a lot of the logic related to that object in sort of spread in a three or four different calling contexts. There are some things that control over here,

some things in the service over there. Sometimes it's duplicated, sometimes it's not, but if you want to understand how this object is used, you have to sort of see it all over as opposed to saying, hey, this is an object that has to do with, I think we were talking about money the other day. Right. Yeah. So maybe all the money really logic should be pulled in and now you have doing methods on money object. Often times there's more primitive values or things where you might

just have a hash. I often find it for doing e-commerce and doing some more complex logic. Often times having a legitimate shopping cart object that owns its own domain operations rather than just have callers constantly be like, oh, well, if you have this thing inside of you, I want to do this. All those sort of, or maybe ways of when the logic is spread outside, that's an enric code, in this case, the shopping cart and the money or the time would be an enric object because it doesn't have its own methods. Yeah. Okay. That makes sense. You're mentioned of the CEO and the

getting a key or something from them. Maybe you think that there's a little bit of an inherent contradiction when I think of as a welcoming code or code-based project, I think a good welcoming code base doesn't require a lot of interaction with other people to get it up and running. But at the same time, a welcoming team is going to be really willing to do that anyway. Like if you, if you have to slack some person to say, hey, I'm setting this up and I need this value, that's built in introduction and opportunity to get to know a team member, but it's also annoying. Right. So, so figuring out a balance of not needing to ask a million people a bunch of small questions,

but also somehow being able to get to know the team while you're getting to know the code base, I think, is ideal for me. Yeah. I think we're getting at maybe the idea of friction here. Yeah. Yeah.

Yeah. Low friction, but not being totally isolated. Right. More people offering to help than you actually need. That's a good sign. I feel like now we're sort of hearing into what makes a team

welcoming. Right. Right. Which is a whole other topic. Yeah. I feel like you were talking earlier

about coding, hearing two patterns or sort of conventions. Maybe there's a sense there that a person should need to know the sort of years of lore behind your app in order to be able to like jump in and do things. Yeah. Those moments where you ask, you join a team and you ask someone like, hey, I'm a little confused about why this is happening here. And they go, yeah. And then

started to a story that's, you know, five years ago, Tony worked here and Tony really liked this. And you know, there's always going to be some elements of that in your app, right? But ideally, I think you want to reduce the amount of like deep lore that you need. Yeah. Sometimes deep lore is the kind of thing where because all of your team shares that, you can lean into that to be more productive. But now there's this like deep implicit knowledge

that everyone on the team must have and that becomes really challenging when someone you join. Yeah. I think the difference between that is kind of how an existing team member responds when you ask them about it. Right. Is it starting with a big sai and a, well, let me tell you or like, oh, yeah, that's an interesting thing. Let me tell you. I think it does not always,

the Lord doesn't have to be like a bad thing that happened or like an interpersonal thing. Yeah. Sometimes it's just some ways where you've gone, I guess quote unquote, off the rails, or maybe even, I'm going to make a, maybe a little bit of a hot take here. So just saying on the rails, there are some ways that your app can be more challenging for a newcomer to navigate. Specifically, if you're using rails as built in fixtures for your tests.

Oh, goodness. I find that so confusing, honestly. And I'm not junior. I think there's a lot to say in favor of fixtures, right there, they're much faster than factories. They can result in less data getting created. But in a sense, you have to like tell a story

and you have to have the sort of deep knowledge of sort of what this app state is when you generate when you start up the test suite and like, no, that, oh, Bob is the user who has misbehaved in the past and has been shadow banned or something like that. And then you see that fixture being called, you know, oh, that's that person. Yeah. Or you know that Alice is the one who's got a shopping cart that she's abandoned. Something I enjoy doing with things like that is choosing a TV show or book or movie or something and using characters from that in ways that, you know, makes sense and kind of fun for someone who's familiar with it, but not like you don't have to be familiar with it source to get it. No one had another layer of lore that they

need to know. Yeah, but it can be a thing where like I was working on a an app where we need a different roles, somebody in admin, somebody in finance, somebody doing more road tasks. And so when I was making tests for that, I used the Casa Parks and Rec and was able to say like, okay, this character is the finance guy. So Chris Shaker is going to be our stand in for the finance role. So when you're, you know, testing and looking at things, it's just a little easier to got instant go. Wait a second, why is the finance guy doing the admin things? Or like who let Andy

Dwyer look at money? I think it can be kind of fun to sort of get to know a new team based on the little gems of that they've dropped around the team I'm working on right now. They've got a staging environment that is a fake company that is basically Strickland Pro being from King of the Hill. And it took me a second because I'm not super familiar with that to understand what was happening, but it was like a, it was a fun moment when I went, oh, these aren't just randomly made up names, these are characters from a TV show. Have there been times where you've been new or maybe not some new to a code base? Maybe you're in the project and it's been six months and then you

stumble across something like, oh, that makes me feel sort of so welcome here. Oh, I think one thing is helpers for setting up complex situations and testing. So sometimes you'll be, you know, writing a test and it touches multiple areas of the app or probably more frustratingly, it's going to require you to create some mock data from like a third party API or something. And having tools created already that help you do that quickly and clearly, I think it's the kind of thing that can really make me feel welcome in a code base. Just like a, oh, I thought that this task was going to involve all these tedious little bits, but somebody has already done those tedious little bits and then encapsulated it in an abstraction that we can all use. And so we don't all have to do those tedious little things anymore. And I can just pull in this

beautiful helper somebody wrote and carry on with the important parts. You're working on a team where people care about the developer experience. Yes. Yeah, absolutely. The start bed is, those moments where you go in and you're like, oof, this is going to be annoying. And then all of a sudden,

that oof turns into an aw, that's actually really nice. Yeah, yeah. Helping each other out, leaving tools around as though it's some sort of video game you're playing and you're exploring and suddenly, oh, there's a shovel right when I need it a shovel. Yeah, I think a really simple one that I've seen on a lot of apps or sometimes I've been the one to create is a sign in as helper for Kathy Bar specs, because almost all specs in your app are going to require sign in as some sort. Yeah. And having something like that, just things starting writing that test so much simpler.

Yeah. Something similar that I created recently that Phil kind of proud of and hope other people love me is we were using like a UI component library that's a little unique in some ways. So writing a system test and trying to do like use the kebabar, like select an option from this menu doesn't work because it's not the standard elements you would expect. Oh, no. Yeah. Right. So

the first time I ran into that, I was very frustrated and ended up writing a helper that is a select and you can remember exactly what it's called, something slightly different than the kid who bear one, but it's got the same basic interface you pass at the field you're working on and the value you want to select and it does just what you expected to. And that felt good. Okay. I'm not going to have to fight this again because I have thought it once and the solution is here. Yeah. I guess part of that is paying it forward as well, right? Ideally, you want to code base

as welcoming for yourself, but when you do run into those jagged edges as a new person, sometimes you're more sensitive to them and like taking the time to say, Hey, you know what, I had to write a test for the first time. It was really annoying. I'm going to take an extra 20 minutes and write a helper. Yeah. Which, you know, is sort of the inverse of like, how do you make it easy to welcome yourself into a team or a code base? Oh, I like the sort of self ownership of that. Yeah. Like, I want to be

a easy to incorporate welcome addition to this team. So when I join and I write my first system test and realize that selects or a pain in the butt and there's not really good way to do it, instead of complaining about that, I can just make my own little helper and offer that up. So I guess yeah, it does go both ways. I want the code base to be welcoming, but I want to be a welcome addition as well. So now I'm starting to think in terms of like things that I like to do that I sometimes benefit from others. And I think that I do a lot is putting a lot of thought into my commit messages.

Oh, yeah. I don't know how many other people read commit messages a lot. I think some people might look at PR or some people just don't at all that I often just my code editor or directly on the command line will get blame a line because it looks weird and like, what why is that line the way it is? And I really appreciate having a note in the commit message that explains any time you've done something weird in the app. Yeah, absolutely. I think it can sometimes be tempting to leave that as a

comment in the code itself. But I tend to not do that. I tend to sort of try to capture those and commit messages instead. But I'm curious, like, when would you want to explain some a strange decision you've made in a comment in the code, if ever, versus a commit message? I feel like I've moved around the spectrum of that sort of self documenting code, no comments to more comments. I'm now in a place where I actually like having comments. There may be not the first

thing I reach for. You know, if a better named method or variable name can better explain something that reached for that, right? If maybe extracting a few things so that you're now writing your method as single level of abstraction, you're saying, hey, this is a like three step process. First, we send an email, then we do some transformation, and then we queue up a background job or something like that. Maybe those are just three high level methods you call and your method is not intermixed with a bunch of low level looping or querying or anything like that. So that's often

maybe where I start. But if you're doing anything really weird and it's just like, why would you do it that way? I often like to leave a comment and say, hey, this is why we're doing it weird. Or if I'm doing something weird, I'm afraid that someone will try to change it back because it looks like I did it wrong. Yes, that's when I was like, leave a comment. This looks wrong. It might be wrong,

but we have to do it this way because the like, don't try to make this correction because you will break things. Yeah. Sometimes you can do that with a unit test, right? And that's always fun. The like, you do a unit test so there's something actually like changes the code to what they think is correct.

The unit test will break, but the message is, hey, this is that case you probably got here because you tried to change this thing. You shouldn't change that thing. Oh man, I've never done that, but I really like the idea of that because sometimes for people it could be tempting to like, oh, I fixed the bad code. And now this test is failing. The test must be bad too. Let me fix the bad test.

Uh huh. And so leaving the error message right there and saying, you may want to, but there's a good reason that this weird thing is happening. I know these things can overlap as well, right? I think there's often value in having a comment and maybe a unit test and a commit message. Yeah. Yeah. And I think

those can be a thing that can make things welcoming too. I think at the very beginning, I mentioned, you know, adhering to conventions and patterns, but I think it's more important to be aware of when you're not and to communicate around why you've made that choice. I would rather have some comments and unit tests and commit messages that say, we did a weird thing. Here's why then someone trying to sort of just pretend I didn't do any weird things. That's fine. It's normal. Yeah. I think that deviating

from patterns and conventions and norms is totally fine. And it's, they can be welcoming when that is, when the team or the developer owns that and is upfront about it. So it's not a surprising or scary moment. Yeah. I've got an article that I often like to go back to is called a hierarchy of documentation.

I'll link to it in the show notes. This sort of looks at all the different ways that we have of documenting our work and how they sort of fit in a cohesive system of well-documented codebase. So that's well worth a read. Yeah. That does sound very interesting.

A moment that I was particularly proud of was we were doing some work on an app and there was some like unexpected education meant to handle for security reasons. There was a potential security vulnerability. So we had to do some unusual stuff to prevent that. And I wrote up practically a blog post explaining the whole reason how it got, how you could replicate it and all of that. And then, you know, got it done. I rotated off the project. I was on a different project. 12 months go by.

And then I get an email from someone who's like, hey, you're the author of some code. And I just was really confused by it. And I read your, I did a git blame and your commit message was so helpful in understanding something that we were not sure why it was there. Oh, that feels good. Yeah. Someone like actually took the time out of their data reach out. Yeah. Because this commit

message that I had left had solved something for them. Yeah. Man, that's so welcoming that it's continued to be welcoming even when you're not there anymore. Yeah. And I guess going full circle sort of thing through talking about at the very beginning, the idea of rotating off as a consultant, I feel like oftentimes because we're on projects for shorter terms than a direct employee of the company, we have to almost double down on making sure that the reasoning behind our decisions is well documented. Yeah, because that can't just live in collective memory. People can't

just slack us because we're going to be gone in six months. Yeah. Yeah. There's a thing like that that's on my mind right now where we're parallel working on implementing a connection to a third party service that's going to return some data and the pieces of our app that then use that data. And I'm working on the pieces of our app that use that data, which means I've had to build in sort of a mock of the data into the app itself. And I'm not going to be around when it's time to

remove that mock and replace it with a real data. How do you ensure that like those decisions persist or at least are visible to the team? Yeah. I tried to mock the data as close to where it will actually be coming in as possible. So instead of doing the mock like in the view or in the react component or even in the controller, I've mocked a method on the, created a method on the model that returns the data in the structure that I have been told it will be coming in. So

ideally, the goal is that that method can be removed and we can just point to where that data is stored on the record instead and everything else should just work. I hope. Yeah. So I've got some documentation and I'm trying to think of like all the ways that I can make this as seamless as possible when I'm gone because I have a very clear intention, but that doesn't matter at all if I'm not there and nobody knows what my intention was. So yeah, I don't think it'll be quite the get an email in 12 months worthy, but I hope that I can leave that in a state that makes people relieved that it's an easier task than they thought it would be. Have you ever used the gem to do or die? Yes, I have. That's the gem

where instead of just leaving to do comments everywhere, you use this gem to create a comment and there's a date on it. And if the to do hasn't been resolved by that date, if there's an error, yeah, only in the, I think, test and development environments. Yeah. Yeah. Those can be both beautiful and frustrating, you know, because you can just set the date later and keep going on with your life if you want to.

And I imagine it's really annoying when you're like the unlucky person who is pushing up your PR and then see eye breaks six months later because of this unrelated change. Yeah. And I guess you get this news button maybe just so that you can deploy and then hopefully you go back and fix it. Yeah, that's a tough choice. Is this PR that I'm trying to merge high priority enough that it's worth just pushing this news button or has the time come and then I am the chosen one who must now face this dragon? It depends how big the dragon is, right? Is this going to be a week's worth of work? Is it 20

minutes worth of work? Yeah. And like, do I have the context for it? Or am I going to have to go hunting? Or is this, you know, still blocked by something else? And I need to go figure out that it's still

blocked by something else and push the to do date down the line legitimately? Yeah. So I guess sometimes a to do or die, maybe is a welcoming thing or at least a way to like help other people know that, hey, there's some decisions that we had, we wanted them done by a certain time over the boundary of someone leaving. But maybe also it's a very unwelcoming thing if someone new issues, the one who has to hit that and then have another big task on their plate or a lot of new things to learn all of a sudden. Yeah, I think that's another one where, you know, the documentation and the context around it can be really helpful. If the to do comment itself explains why we're not fixing this right now,

what needs to happen before we can and how we need to fix it, that's awesome. If it's just like to do fix this by January 1st, when I know I'll be on vacation. Good luck. And it's a little less welcoming. Yeah, I mean, that's, you know, I think we've looked at a lot of different ways that maybe we've felt welcomed in a code base or ways that we try to do to make things welcoming for others.

Any final thoughts on this topic? You know, I think like most things, it comes down to communication. It really does really like how well has the team communicated their intentions and decisions. Yeah, that's way to summarize it. Yeah. On that note, shall we wrap up? I think we shall.

Frequently asked questions

How long is this episode of The Bike Shed?

This episode is 39 minutes long.

When was this The Bike Shed episode published?

This episode was published on January 13, 2026.

Is there a transcript available for this episode?

Yes, a full transcript is available for this episode. You can read the complete transcript on the episode page.

Can I download this The Bike Shed episode?

Yes. Use the download control on the episode player to save the publisher-provided media file.