This episode is brought to you by WorkOS. If you're building a B2B SaaS app, at some point, your customers will start asking for enterprise features like single sign-on, SCIM, provisioning, role-based access control, and audit trails. That's where WorkOS comes in, with ease-to-use and flexible APIs that help you ship enterprise features on day one without slowing down your core product development. Today, some of the hottest startups in the world are already powered by WorkOS, including ones you probably know, like Perplexity, Vercel, Jasper, and Webflow. WorkOS also provides a generous free tier of up to 1 million monthly active users for its user management solution.
making it the perfect authentication and authorization solution for growing companies. It comes standard with rich features like social logins, bot protection, MFA, roles, and permissions, and more. If you're currently looking to build SSO for your first enterprise customer, you should consider using WorkOS. Integrate in minutes and start shipping enterprise plans today. Check it all out at WorkOS.com. That's WorkOS.com.
Hello, and welcome to another episode of The Bike Shed, a weekly podcast from your friends at ThoughtBot about developing great software. I'm Stephanie Min. And I'm Joel Kenville. And together, we're here to share a bit of what we've learned along the way. So, Joel, what's new in your world? What's new in my world is kind of an old thing that has resurfaced. Long-time listeners of the show will know that I'm a big fan of two things, chunking up work into smaller pieces and dependency graphs. And recently, I got a chance to sort of blend those two together, give a presentation on how leaning on dependency graphs can help you to chunk up your work and work in a more iterative fashion.
Cool. How did you get to do that? So the team I'm on at ThoughtBot, every other week, somebody will do some kind of presentation. And I volunteered for this quarter and chose to talk about that. Inspired by some recent client work where there's a really gnarly problem that I was able to break down into a bunch of smaller pieces in a way that was really successful. If I had not chunked it up, I think that initiative would have been at risk just because it was kind of an interrelated ball of features that just kept growing. And if I hadn't been very disciplined about doing things in small pieces, it's the kind of thing that could have gone on for multiple weeks and just never gotten done.
a body of work that you did ended up being broken out into 19 PRs or something like that? Is that the problem that we're talking about? I think that is the one, yes. I may have even mentioned it on the podcast at one point when I was going through that work. But now I got to build on it and actually share. So I got to be there for that presentation. And one thing that I always really like with the stuff that you share at our biweekly meetings is you find just really great examples from client work to kind of share a learning from with the rest of us. And they end up being really good examples for doing exercises like that. I'm wondering, do you think that sharing it with other people
give you new thoughts on the problem that you had been doing on your own? I think it gave me an appreciation for how complex the problem was because trying to explain it to other people in a sort of group presentation setting where you don't want people's eyes just to glaze over was challenging. And so I actually simplified the problem down because I didn't want 19 PRs worth of work to be discussed there. So I simplified the problem and really just found an element to highlight of like, here's why it's complex and why everything's interrelated. If you pull on this string, you think there's an easy solution, but there's always a like, oh, but you can't do that because this. And you're like, all right, well, let me do this thing. Oh, you can't do that because of this. And you kind of end up boxed in. And then we look at how.
Instead of brute forcing the solution, you can do it with a dependency graph and it just gives you a very clear approach. And for what it's worth for our listeners, what I suggest is that you take your problem, decompose it into a list of things, but oftentimes you can't just work linearly through a list top to bottom. So then you take that list of things and draw connections. What is blocked by other work? And then when you've done that, you end up with a dependency graph where the arrows point to things that are blocking other tasks. And then at that point, you just sort of work from the leaf nodes back to the root and each node should be able to be done and shipped independently because it has no dependencies.
no blockers. And you just kind of follow that pattern and you end up back at the root and then you've done all the tasks and potentially have like deployed to production multiple times. I think hearing it sounds potentially simple, but the work of decomposing the really large complex problem, that's the hard part, I think. And so there were a lot of times that I got the sense that you were kind of being like, okay, I think we can break it down even further or like we still might be blocked here by something else. And having someone guide you through that exercise, I think is really useful because you aren't always able to see what might be blocking yourself. Sometimes you need...
another perspective or someone who just has a lot of practice kind of thinking in that way. The thing I try to do with that work is not go from like a, oh, draw two circles, draw the rest of the owl. That's not a fun exercise for anyone. And for our listeners, this was not just a presentation where I talked. This was a presentation that was interactive. It's almost kind of workshop where I gave a simplified scenario version of the task it worked on and asked people to then build a dependency graph that represented the work to be done. So Stephanie, what's new in your world? So I recently wrapped up a client project and off-boarded. But one thing that happened that I was not expecting, and I don't know if this is like the first time that I've experienced this, but it has been a little while.
where I was not able to finish my project in time for when I had to be wrapped up with the team. So I've been working on this really ambitious and pretty big project for a couple months now. And all that time, I really was feeling pretty sure that I would be the one to see it through because that was kind of how we had planned it and how it had been estimated. But as we got closer to the deadline of me and my client project finishing, it became clear that that wasn't going to happen. So I had to shift into handoff and knowledge transfer mode and make sure that...
I got a chance to meet with the people who were going to take it over and essentially release it in production. And this was, you know, this was a big change. Like it was rather risky and I had done so much work to make sure that it would go as smoothly as possible, but there was still a lot of stuff that was kind of internalized in my head, right? About all the things that needed to happen, all the people to talk to, like all the check marks to take off. So yeah, I was really nervous, but.
I think that nervousness and anxiety about what could go wrong actually fueled me to be extra motivated to make sure everything was kind of all the loose ends were tied up because I really didn't want this to be like a tricky and like troublesome feature release for people who hadn't been as close to it as I was knowing that it was quite complex. So it almost like lit a fire under me to like get everything documented. And I even refactored some things because I was like, oh, like this is maybe a little confusing. Like, let me be in someone else's shoes and see how I can make some of this code a bit more clear to understand just in case they need to debug it, right? And I've buried the lead a little bit here, but it went off smoothly. I even checked it on kind of the day that it was going to go out and just be like, how are things looking for this feature that I worked on, you know, after kind of just from the perspective of a user. And I was really happy to see that it worked out. That's always great news when you circle back and people are like, yeah, no, the work you did was amazing. What would you say are sort of the main things you worked on to make that handoff really smooth? You mentioned you did some refactoring. I had done some refactoring. Part of the challenge here was that the releasing of this feature kind of required some coordination with the infrastructure team and a series of steps that needed to be taken.
And I made sure to basically write up a little runbook for releasing this thing and what parts of it was like an application developer's role and what part of it was a DevOps engineer's role. Because I had also at that point kind of been managing and organizing all of that. And we ended up doing a little test run on staging, almost like a rehearsal with the folks who were going to be taking it over for me. And yeah, I really wanted to make sure they felt as confident as possible. I knew that there was always going to be a sense of like, you don't know what you don't know, right?
They were all feeling fine. And I was the one who was like, I don't know, like I'm nervous because I knew all the intricate details of things that could go wrong. But I think, again, I guess maybe this is why anxiety has some kind of purpose as an emotion because it really got me into the headspace of wanting to make sure everything was in place. I will say that I did notice one issue afterwards and I had to really fight the urge to, I was like, I could email someone and tell them, like, I think I know how to solve this bug that I'm seeing. But I also was like, like, I kind of want them to go through the process of.
they should be self-sufficient enough to be able to figure it out, right? And I almost think that it was a little better that way that I was like, it is yours now. So that experience will be valuable of digging into the future that I contributed. How did you factor in the use of the test suite as a way to help the team transition? Ooh, I was very diligent about the test that I wrote. Because I was on this solo, I knew I wasn't going to be around forever. And in fact, a lot of it was integrating with some existing code that I think not a lot of people on the team had familiarity with. And so this was kind of the first time that they had to work with some parts of the system in quite a few years. And some of the newer folks on the team had never really dug super deep into that existing code. So as I was integrating with it and...
extending it essentially, I really wanted to make sure that it didn't become the thing that I had to deal with where I was asking people questions about like, how does this work? And no one would respond. Not because, you know, just because they didn't know, right? Not because they didn't want to help. And so I did a lot of work to detangle that. And yeah, it was a lot of stuff that was just hard to reason about. And I am very thankful that I was able to lean on tests to both like process it for myself and then also have an artifact afterwards of like the work that I did to kind of understand what the code was doing.
Interesting. So you mentioned both helping you learn, but also like a thing that you can pass on to other people. I've not heard at all speak of verifying that the code works or sort of correctness, which I think is what most people get for value out of a test suite. In a situation like yours, do you think there's value for a test suite beyond just that verification aspect that we all sort of know and love from a test suite? Yeah, 100%. This experience actually inspired a blog post that I wrote about this very thing because I got to really see the value of how writing tests helped me.
just feel more confidence in working on an unfamiliar code base and then being asked pretty quickly to start developing new features that also integrated with the existing code. And I think I have really made it part of my process to read tests or to whenever I'm getting into editing a file that already exists, going to the test first, seeing what's covered, seeing if I do need to backfill any test coverage. And this time, not just reading them, but even going through the process of writing the tests. again, myself, oftentimes because the test code was also quite complicated and I didn't really understand it either. And it actually ended up hindering me in some cases. So I was like, oh, like, screw it. I think if I really want to understand this code enough so that I can change it, I think I need to write the tests myself. And yeah, that ended up being almost like a bit of a superpower because the parts of the code base that, you know, every team has that like, yeah, that part of the app is really complex. We're all like kind of nervous about it. You know, whenever we make changes, things have gone wrong, that kind of thing.
Somehow I became the person on the team who knew most about it by going through that process of being really diligent and understanding what was going on and almost like proving that to myself by writing tests for them. I feel like in my experience, there's nothing that gives you as deep a knowledge of some code. Actually, there's two things. One, writing sort of method-level documentation for undocumented code. That absolutely gives you an in-depth knowledge. And then backfilling tests for code that has not got any test coverage. Those two things cause you to become sort of intimately familiar with all the edge cases in a way that just reading through the code doesn't. Yeah, I like the phrase intimately familiar because that's definitely what it felt like. I think you also develop more than just an understanding. You kind of have to develop your own opinions about it as well.
A few weeks ago, I mentioned that testing workshop that I took and it was all about the idea of good enough testing. Like, you know, you can try to cover every condition under the sun, but you probably don't want to because time is finite. And so what does it mean for test coverage to be good enough? And like, how do you know what things you do want to make sure to test then? And that when you are like reading existing code and you don't have someone to tell you like, oh yeah, like this is probably going to be the behavior that happens like 90% of the time. And this is just like an edge case that we really, really don't think like will happen at all.
but it's here anyway. I think in some ways you need to like determine that for yourself. And that process of figuring out what good enough looks like to you, I think is one way of forming your own opinion about not just understanding what's going on in the code, but what it means in the broader picture of the product or the user interaction or whatever. This episode is sponsored by MailTrap, an email delivery platform that developers love. An email sending solution with industry best analytics, SMTP and email API, along with SDKs for major programming languages and 24 seven human support. Try for free at mailtrap.io.
You mentioned that for some of these things, you're sort of backfilling in your own test coverage, but you're also sometimes looking at existing tests as well and almost using them as a form of documentation. How do you feel about reading tests? Because I feel like I love the idea in theory that a spec acts as documentation. And in practice, I find that I really struggle reading tests. Maybe it's because as Ruby, we tend to lean towards making tests easy to write and hard to read. So going into an existing code base and reading tests is hard. Maybe I just need to get better at reading tests, but I feel like I should default to reading tests if I want documentation. In practice, I would prefer almost any other form of documentation.
including inline comments in the code. Wow. Okay. That's really interesting. I don't think I've heard that from you before. And that like surprises me quite a bit, but I think I understand what you mean. It's like in practice, it ends up not being that useful because I think most test code is not good for reading, but I have experienced like reading a really great test. And now knowing that that's what that can look like, I'm like constantly seeking that out or trying to do it myself so that other people might also enjoy a similar experience. Yeah. Can you tell me a bit about why you don't enjoy it or find it?
difficult? It requires a lot of effort and sifting through a lot of noise. A thing that's hard to get with a test is just the right level of abstraction. We've talked about this on a previous episode where if I'm coming in as a reader, I'm not just distracted by all this noise of random stuff that doesn't matter. And then I have to put a lot of effort in to figure out what is actually going to tell me the thing I want to know. People have put all their localized context in the test. Or on the other end, if they've really heavily abstracted it, then I'm following all these method chains and jumping to definition all over the place just to get a sense of what's happening. You look at the test case and it's just like, it does the thing. And you're like, well, great, that doesn't explain anything.
If this was a line of documentation as a comment in the method, it would just be repeating the method name and that would be useless. So a test like that is not helpful when reading. But also a test that has everything localized can be just so noisy that it's hard to figure out what actually happens. Yeah, I think that makes a lot of sense. And it's one of the reasons why I actually have shifted to when I do write tests, like almost then going into that editor or reviewer mode of like, OK, I've written this test. What in here actually is noise and what?
things do I want to highlight? So maybe that means making a test variable even more clear about what it is rather than just hoping that they'll figure it out from whatever traits I've included in the factory. Or sometimes if like there's an association that's required to create a factory, but really doesn't have anything to do with the test itself, I will maybe like inline that instead of having it pulled out a variable just to kind of, again, highlight that you don't really need to look at this. But I hear you that I think most people don't do that. And they kind of just put in all the things, all the localized things they need to get it to pass. And sometimes it's a lot.
which I think I've started reading almost like as a challenge or an opportunity to rewrite it and see if I can make some improvements there. And also as information about either how the team approaches testing, treats testing, how coupled the code is. I think that is super duper clear in test. I think you're bound to definitely start to feel that as you're developing later, but it is always kind of interesting to see that you can even observe that like in just how the test setup is. At least, you know, maybe you get some sort of idea about what you're having to deal with. So you gave a talk at RailsConf on tests as a way to handle or to surface underlying complexities in your code. I would love to see sort of the reverse of that, a talk on how to write tests that are actually readable, that aren't focused on like all the other benefits of tests that we left. You know, TDD helps you with design or, you know, they help verify your code or all these other things and really lean into this idea of tests as documentation. Tests that are meant to be read by someone who's not you in the process of writing it. And how can we make that better? Yeah, I think.
For me, one of the most compelling value propositions of tests is that they are truly living documentation of your system. I mean, they won't get outdated because then they would fail and they would either be updated or removed. And maybe it is a little bit pie in the sky for me to think that tests can really serve that function because like you said, in practice, a lot of times it's really difficult to read them and you don't get the information that you're really needing. But I do feel more and more motivated to kind of pursue that as the goal because it just makes sense to me. I do think that over my career, I've definitely started emphasizing readability as a thing that I want out of both my app code, but also my tests as much as possible. You can optimize for a lot of things. I'm going to write code that's the fastest possible. Or I've been on teams where you're actually trying to write it like the shortest possible. You're kind of like code golfing. And I think over the years, I've definitely migrated a little bit towards the camp of your code should be as readable as possible because another person is absolutely going to need to read my code at some point. Yeah. The whole theme of that blog post that I wrote.
Essentially, it's this idea that your test environment is this treasure trove of information about your application, because it literally is just a whole other environment for you to learn about it and interact with it and play with it and get feedback. And I'm surprised that there's still such a focus on tests and correctness when I think that they can be used for a lot more and can provide just a lot more safe and fast and cheap place to try things out in your code, get immediate feedback. inspect things a little more quickly without having to do manual setup or cleanup. Yeah, all that good stuff. The idea of a living specification is incredibly compelling. Joel, I'm curious if you have any immediate thoughts on how your test suite can be valuable besides making sure your code works. I think that one of the classic answers to that is that if you are test driving your code, you write your test suite first, it actually influences the way you will write your code. And because writing tests for tightly coupled code is really annoying, in theory, you would write tests in a way that
would want code to be not coupled to avoid that pain, which then leads to typically more decoupled designs. And I think that was the point of your RailsConf talk this spring. So that's the first thing that comes to mind. Yeah, I think one of the things I think I remember saying in that talk was that writing tests, it's like basically the first time you're really applying the code you've written and you can start seeing how it interacts with other things, especially if you're test driving, then it's like you're only focused on connecting the pieces that need to be connected together. you haven't gotten to the point of like, oh no, I now have things that are tightly coupled because you are kind of only introducing the minimal amount of things integrating with another to make your test pass. Speaking of test driving, I was recently shared another article about the idea of scrapping any code you write at the end of the day if you're not done and starting fresh the next day. The author did say, you are allowed to keep your unit tests, which I really liked because the point of that is to just stimulate new ways of solving the problem.
Now that you have some experience with it, maybe you can see new angles or kind of know what you'll need to dig deeper into. But the idea that once you have your test in place, that being a safety net to allow you to do whatever, try whatever other ways of writing the code, that was also really cool. Because yes, it's able to do that because it's the thing that makes sure that your code is working. But at the same time, it almost plays a role of like, I don't know, it's like, I got your back kind of thing. And enabling a little more kind of creativity in writing the code.
knowing that you've kind of already gotten the part of it working nailed down? It allows you to try sort of multiple different designs if you want to, which is pretty fun. So you've got the test suite, you keep it, you try one design, you don't like it, or you try another branch, try a different design, like maybe both of them pass the test suite, but they're very different. And then you can sort of compare them side by side and decide what you like. On like a commercial project, I rarely reach for something like that, but I will do it occasionally. I think where this comes up a lot is when you want some sort of like shared exercise or like Cohen or something like that. And so I'm thinking of something like exorcism.
which is a website where you can sign up to do a bunch of problems in different languages. They give you a test suite and your job is to make that test suite pass. And then you upload your solution and you get to compare it with other people's. And that's a great way to like learn some things on your own and practice things. But then also the comparison, you say, oh, somebody else passed that test suite with a very different set of code. Now that's interesting. Yeah. Oh, cool. Okay. I think, yeah, it does feel more like what you said earlier, like a specification, right? And that still feels different from when you write your test afterwards. For some reason, just like the inverting that process, at least for me, gives tests.
a more interesting usefulness, essentially. I want to bring up another use for tests, which is now like less than the like, here's like, it's always useful in this way. And like, it's very detailed. And I'm kind of zooming out a little bit. But tests is accountability. If you put up a PR and there are no tests in there, I'm not 100% sure that the code that you ship actually works. Because you probably tried it on your machine, but you may have made a last minute tweak before you push it up that just like fundamentally broke it. Like you introduced a nil error somewhere that just means that on the first screen, it crashes and nothing can happen from there. And if we went into production, that would just break. So...
I don't even need to see the contents of your test suite, but knowing that there are tests on your PR already increases my confidence that the code you're shipping actually works. That's great. Yeah, I like that a lot. It's almost like test of the smoke test or test suite is a smoke test. Yeah, because you know, baseline, it should pass these tests because they exist. Or even, I don't even need to know that CI is running and like, oh, your CI is green, so you're good. But the fact that you wrote tests for your feature already increases my confidence in your PR. Yeah, I really like that.
Keyword accountability. I actually can think of one time that I changed some code in an untested file and I didn't backfill a test for it because I was rushing. It was Friday and I had renamed a method and I had forgotten to update one of the places that it was called and someone had to call it out in code review and asked, is there a test for this or why isn't there a test for this? And I felt a little embarrassed and I was like, you're right, there should be a test for this. So I will add one now. But I appreciated the accountability in that situation because I literally would have introduced broken code.
And ship it on a Friday. And ship it on a Friday, exactly. So yeah, it's almost like a way of just like looking out for each other and your teammates and just being like, yeah, helping each other build the trust that you've done the due diligence. I'm curious, digging into the idea of tests as like an aid for code review, do you ever focus on the test suite in code review to help you understand what a PR does? Like it's similar to the idea of like tests as documentation, but I feel like in this context, it's a very specific context that sometimes it's a little bit different. Yeah, I think they can supplement or even provide more granular detail because, you know.
Oftentimes, people will leave in their commit messages or maybe in the PR description kind of details about their change. But I don't do this often. But I do know that I have read the test first just to get an idea about what I'm going to be seeing in the code and just being like, OK, here are the different conditions that they are solving for or wanting to make sure are covered. And it kind of primes my brain a little bit to know what's coming in the code. Because sometimes if you're just dropped into, I don't know, whatever file happens to be first in the PR review, you don't have as full of a picture about what anything is really about.
Back in the day, I used a browser plugin that would reorder the files on GitHub so that the tests were always at the top rather than being ordered alphabetically. It would just take the spec directory and move it to the top of your GitHub diff so that you would read the tests first. And I don't know, at some point, maybe it stopped working or something like that, but I fell out of use of it and hadn't thought of it for years until we just mentioned reading tests first here. And I was like, oh yeah, I used to have a Chrome plugin for that. Wait, I like that a lot. I will go and seek out something like that after the show because I think it would be really useful. And I mean, they have it of doing that more frequently because for some reason, I think they always end up at the bottom.
But I'm very curious if just having that be the default behavior for me shifts the way that I review code. If it ends up being easier for me to review because I'm seeing what's going on in the test first. So not test first development, but test first review. Ooh, I like that a lot. I think maybe we are onto something here.
So I hope that this conversation inspired any listeners to rethink what tests are for and what they can be useful for. I think that it's really cool that they're able to play all of these roles and help me become a better developer. I think I really, once I started seeing why testing was important beyond just the green checkmark and knowing that it was like catching bugs, I have felt a lot more confidence and trust in my process as a developer. Yeah, I think this conversation has inspired me to lean more heavily on test review. rather than sort of a after the fact thing that I do at the end of a PR. So maybe that's just learning to scroll down when I see a new PR. Maybe that is like hunting down to see if there is a browser plugin I can use. On that note, shall we wrap up? Let's wrap up. Show notes for this episode can be found at bikeshed.thoughtbot.com. If you enjoyed listening, one really easy way to support the show is to leave us a quick rating or even a review in iTunes. It really helps other folks find the show. If you have any feedback or questions, you can reach us at hosts at bikeshed.fm via email. Thank you so much for listening to The Bike Shed and we'll see you next week. Bye!