Stephanie discovered a new book: The Staff Engineer's Path! Joël's got some D&D goodness.
Together, they revisit a decade-old blog post initially published in 2013, which discussed the application of Sandi Metz's coding guidelines and whether these rules remain relevant and practiced among developers today.
JOËL: Hello and welcome to another episode of The Bike Shed, a weekly podcast from your friends at thoughtbot about developing great software. I'm Joël Quenneville.
STEPHANIE: And I'm Stephanie Minn. And together, we're here to share a bit of what we've learned along the way.
JOËL: So, Stephanie, what's new in your world?
STEPHANIE: So, I picked up a new book from the library [laughs], which that in itself is not very new. That is [laughs] a common occurrence in my world. But it was kind of a fun coincidence that I was just walking around the aisles of what's new in nonfiction, and staring me right in the face was an O'Reilly book, The Staff Engineer's Path. And I think in the past, I've plugged The Manager's Path by Camille Fournier on the show.
And in recent years, this one was published, and it's by Tanya Reilly. And it is kind of, like, the other half of a career path for software engineers moving up in seniority at those higher levels. And it has been a really interesting companion to The Manager's Path, which I had read even though I wasn't really sure I wanted to be manager [laughs].
And now I think I get that, like, accompaniment of like, okay, like, instead of walking that path, like, what does a staff plus engineer look like? And kind of learning a little bit more about that because I know it can be really vague or ambiguous or look very different at a lot of different companies. And that has been really helpful for me, kind of looking ahead a bit. I'm not too far into it yet. But I'm looking forward to reading more and bringing back some of those learnings to the show.
JOËL: I feel like at the end of the year, Stephanie, you and I are probably going to have to sit down and talk through maybe your reading list for the year and, you know, maybe shout out some favorites. I think your reading list is probably significantly longer than mine. But you're constantly referencing cool books. I think that would probably be a fun, either end-of-year episode or a beginning-of-year episode for 2024.
One thing that's really interesting, though, about the contrast of these two particular books you're talking about is how it really lines up with this, like, fork in the road that a lot of us have in our careers as we get more senior. You either move into more of a management role, which can be a pretty significant departure from what you have to do as a developer, or you kind of go into this, like, ultra-senior individual contributor path. But how that looks day to day can be very different from your sort of just traditional sitting down and banging out tickets. So, it's really cool there's two books looking at both of those paths.
STEPHANIE: Yeah, absolutely. And I think the mission that they were going for with these books was to kind of illuminate a little bit more about that fork and that decision because, you know, it can be easy for people to maybe just default into one or the other based on what their organization wants for them without, like, fully knowing what that means. And the more senior you get, the more vague and, like, figure it out yourself [laughs] the work becomes.
And it can be very daunting to kind of just be thrown into that and be like, well, I'm in this leadership position now. People are looking to me, and I have all this responsibility, but, like, what do I do? Yeah, so I'm kind of enjoying this book, that is...it's not a technical book, which is actually kind of what I like about it. It's actually more of a leadership book, which is really important for that kind of role. Even though, you know, they are still in that IC track, but it does come with a lot of leadership responsibility.
JOËL: Yes, leadership in a very different way than management. But—and this may be counterintuitive for some people, especially earlier on in their careers—going further up that individual contributor track doesn't just mean getting more intense technically. It often means you've got to focus on things more like leadership, like being a bit more strategic, aligning technical initiatives with strategic goals.
STEPHANIE: Yeah, and having a bigger impact and being a force multiplier, even in both the manager and, like, the staff plus role, like, that, you know, is the thing that ties the rising level.
JOËL: Yeah, in many ways, maybe the individual contributor track is slightly misnamed because while, yes, you're not managing a sort of sub-organization within the company, it's still about being a force multiplier.
STEPHANIE: Yeah, that's a really great point [laughs]. Maybe we'll be able to come up with a better [laughs] name for that.
JOËL: I've mentioned several times on this podcast that I've been enjoying playing Dungeons & Dragons, D&D, with some friends and some colleagues. And something that was particularly fun that some friends and I did this summer is we hired a professional DM to run one shot for us. And that was just an absolutely lovely experience. Well, as a result of that, I am now subscribed to this guy's newsletter. And he'll do, like, various D&D events at different times.
One thing that was really cool that I found out recently...as we're recording this, it's the week before election day in the U.S. And because a lot of voting happens in schools, typically, schools have the day off. And so, this guy sent out an email saying he was offering to run a, like, all day...effectively, a little mini-D&D camp for school-age kids on election day so that you can do your work. You can go vote, and you don't have to...basically, he'll watch your kids for you and, like, get them introduced to playing D&D, which I think is just a really cool thing to do.
STEPHANIE: I love that. It's so heartwarming [laughs]. And it's such a great idea because, oftentimes, people are still working, and so they need childcare, like, on those kinds of days. And yeah, I think D&D is such a fun thing for kids to get into, too. You know, it requires so much, like, imagination, and I can imagine it's such a blast.
JOËL: I got that email, and I was like, that is such a perfect idea. I love it so much.
STEPHANIE: I wanted to plug my D&D recommendation. I'm pretty sure I have mentioned it on the show before. But there is a podcast that I listen to called Not Another D&D Podcast, which is, you know, a live play Dungeons & Dragons podcast campaign that's hosted by these comedians, formerly of CollegeHumor, and it's very fun. I always laugh.
They have this, like, a kind of offshoot of the main show that they do called D&D Court, which is very fun. Because, as you were saying, like, you know, you hired a DM to run your game. And I know that...I'm sure lots of people have fun stories about their home games and, like, the drama that happens [laughs] with their friends.
JOËL: Absolutely. Absolutely.
STEPHANIE: And so, with D&D Court, listeners can write in with their drama or their conflicts and get an official ruling from the hosts about who was right [laughs] in the situation that they write in about.
JOËL: So, you get to bring your best rules lawyering to the D&D Court.
STEPHANIE: Yeah, exactly [laughs].
JOËL: That sounds kind of amazing.
Recently, I had someone reach out to me asking about an older blog post that we'd written about the Sandi Metz Rules. This blog post was initially published in 2013, so ten years ago, and was talking about some guidelines that Sandi Metz at the time was talking about that she was using in some of her code. And we talked about how our experience was applying those to some of our work as well. And so, the question was, you know, ten years later, is that still something that thoughtbot developers like to follow in their code?
We'll link to the article in the show notes. But I'll just read out the rules here real quick. So, there's four of them. The first one is a class can be no longer than 100 lines of code. The second is a method can be no longer than five lines of code. The third is pass no more than four parameters into a method, and hash options count, so no getting clever with those. And then, finally, controllers can only instantiate one object. You only get one instance variable. And views can only talk to that one instance variable.
Had you or are you familiar with these rules? Is that something that you think about or use in your daily writing of code?
STEPHANIE: Yeah. So, when you proposed this topic, I had to revisit these rules. And I can't recall if I had seen them before. They seemed familiar. And I've read, you know, a couple of Sandi Metz's books, so maybe those were places where she had mentioned them.
But the one thing that really struck me when I was first reading the rules was how declarative they were in terms of, like, kind of just telling you what the results should be without really saying how. So, for example, the one where you said, you know, a method should not be more than five lines [laughs], I had the silly thought of, like, well, you could just, you know, stuff everything into a single line [laughs] and just completely disregard line limit if you wanted, and it would technically still follow the rule.
JOËL: If they didn't want us to do that, they wouldn't give us semicolons in Ruby.
STEPHANIE: Exactly [laughs]. So, that is kind of what struck me at first. Is that something you noticed?
JOËL: I think what is interesting with them is that there's not always a ton of rationale given behind them. Our article talks a little bit about some of the why that might be helpful and how that might look like in practice. I'm not sure what Sandi's original...I don't know if it was one of her books or maybe on a...it might have been on a podcast appearance she talked about them, so she might go more in-depth there. But yeah, they are a little bit declarative. It's just like, hey, here's...it's almost basically the kind of thing that can be enforced by a linter, which is perhaps the point.
STEPHANIE: Ooh, that's really interesting. It's like, on one hand, I like how simple they are, right? It's like, they're very obvious. If you're not following them, you can tell. But on the other hand, they seem to be more of a supplement to the gained knowledge and experience that you kind of get from knowing how to implement those rules. I think you and I will both agree that we don't want to stuff everything [laughs] into a single line with semicolons. But if someone who maybe is newer to development and is coming to these rules, I think they might be wondering, like, how do I do this?
JOËL: Do you follow these rules in your own code?
STEPHANIE: I think the ones that are easier to follow, for me, and that I think I've come to do more instinctually, are the rules about class line length and method line length just because I'm kind of looking out for opportunities to pull out a method or, you know, make sure that this class is just doing one thing. And if it's starting to seem to cover a couple of different responsibilities, I'm a little bit more on the lookout. But I do like these rules as like, you know, like, hey, once you hit, you know, 100 lines in a class, like, maybe that's your cue to start thinking about opportunities for extraction.
JOËL: Do you sort of consciously follow these rules or have them maybe even encoded in a linter? Or is it more you're following other things, and somehow, it just lines up with these principles?
STEPHANIE: I would say that, like, I'm not thinking about them very actively. But that could be a very interesting exercise, and I think, you know, that's what folks did in the blog post. They were like, hey, we took these rules, and we really kept them in mind as we were developing. But I think kind of what we were talking about earlier about, like, what we've learned or the strategies we've learned to implement kind of converge on these rules. And the rules actually are more of the result of other ideas or heuristics that we follow.
JOËL: I mean, you dropped the keyword heuristics there. And I think that brings me back to an earlier episode we did where we talked about heuristics. And one of the things that came up on that episode was the idea that, oftentimes, we use heuristics as a way to sort of flatten a lot of experience and knowledge into sort of one, like, short rule, or short phrase, or something, one guideline, even though it's sort of trying to just summarize a mountain of wisdom.
And so, oftentimes, you can look at something like these rules and be like, okay, well, what's the point? Or maybe you even just follow it to the letter without really thinking about the why behind it, and that can sometimes be problematic. And on the other hand, you might know all of the ideas that go behind them. And without necessarily knowing the rule itself, you just kind of happen to follow it because you're intimately familiar with all of these other software principles that converge on those same ideas.
STEPHANIE: Yeah, agreed. I think that the more interesting ones to me are the no more than four method arguments and only one instance variable per controller.
STEPHANIE: I'm curious if those are sparking anything for you [laughs].
JOËL: I think the no more than four method arguments, to me, is probably the least controversial. It's generally accepted that having many arguments to a method is a code smell. And there's a few different code smells that are related to that. There's forms of coupling incandescence; there are data clumps, things like that.
I've often heard a sort of rule of three. And so, if you're going more than three, then you might want to revisit the structure of what you're building. Four is a bit of an arbitrary cut-off, I'll agree. Most of these are arbitrary cut-offs. But I think the idea to maybe keep your method to fewer arguments is generally a good thing to do.
STEPHANIE: I liked that the rule points out that hash options account because I think that's maybe where people get a little more hand-wavy, or you have your ops hash [laughs] that can be just a catch-all for anything. You know, it's like, once you start putting stuff in there, I don't know, I feel like it's a like a law of the universe. It's like, oh, people will just stuff more things in there [laughs]. And it takes obviously more effort or, like, specific energy to, like, think through what those things might represent, or some alternative ways of handling those arguments.
We definitely do have, I think, a couple of episodes on value objects. But that's something that we have talked a lot about before in terms of, you know, how can we take some kind of primitive data, hashes included, and turn them into a richer object that can then be passed on its own?
JOËL: Right. And an options hash is generally...it's too much of a catch-all to really have an identity as its own sort of value object. It doesn't really represent any single thing. It's just everything else bag of data. One thing that's interesting that the article notes is that a lot of the helpers in Rails take a lot of arguments and that it is absolutely not worth trying to fight the framework to try to follow these rules. So, the article does take a very pragmatic approach, I think, to the idea of these rules.
STEPHANIE: Yeah. And I think there is even a caveat to the rules where it's like, you can break them if you have a good reason, or if you're working with someone else and they give you the thumbs up [laughs], which I really like a lot because it almost kind of compels you to stop and be like, do I have a good reason of doing this? Just making sure, or I'll run it by a friend. And shifting that, I guess, that focus from kind of just coding from, like, your default mode of thinking to a more active one.
JOËL: Right. There is a rule zero, which says you can break any of the other rules as long as you convince either your pair or your reviewer to give you a thumbs up on breaking the rule.
So, you'd mentioned the fourth rule about a single instance variable in a controller kind of was one of the ones that stood out to you. What is particularly striking about that rule?
STEPHANIE: I think this one is hard to follow, and I think the blog post mentions that as well. Because at least I've seen our web applications grow more and more complex. And it can be really challenging to just be like, what is this page doing? Like, what, you know, data does it need to know? And have that be the single thing. Because really, a lot of our web apps have a lot of things [laughs] that they're doing, and sometimes it feels like you have to capture more than one object or at least, like, a responsibility in this way.
I think that's the one that I, you know, in my ideal world, I'm like, yeah, like, we have all these, like, perfectly RESTful routes. And, you know, we're only dealing with, you know, a single resource. But once you start to have some more complexity, I think that can be a little more challenging.
JOËL: I think it's interesting that you mentioned RESTful routing because I think that is maybe one of the bigger things that does trigger having more instance variables in your controller actions. If you're following sort of the traditional Rails RESTful routes, every page is generally focused on a singular resource. Now, that may not necessarily line up with a table in your database, and that's fine. But you're dealing with a singular thing or perhaps, you know, in the case of an index page, a singular collection of things, which can be represented with a single instance variable.
Once you start adding custom routes that may not be necessarily tied to a particular resource, now you can very easily kind of have a proliferation of all sorts of different things that interact with each other because you're no longer centered on a single thing.
STEPHANIE: Yeah, that's true, which actually reminds me of something we've talked about before, too, when we were both reading Sustainable Rails. The author talks about custom routes and actually advocates for making all routes RESTful. And if you need a vanity URL or something like that, you can always alias it. That I liked, right? It's like, okay, even if, you know, your resource is not something that's like, ActiveRecord-backed, is there some abstraction or concept of a resource in there?
And I actually did really like in the blog post in the example; that is one that I've used before, too. They were dealing with this idea of a dashboard, which I would, you know, say is pretty common in a lot of web applications these days. And it's funny because a dashboard can hold so much data, right? It's really, like, a composite of a lot of different things, you know, what is most, like, useful for the user to see in one place. But they were in the blog post. And this, again, this is kind of something that I've done before. They were able to capture that with the idea of, like, a dashboard as an object and that being codified using a presenter or a facade.
JOËL: Right. So, instead of having a group, and a status, and a user, and all these, like, separate things that your page that you're showing is a sort of collection of all these different types of objects, you wrap them together in a dashboard object that's kind of a facade. And I guess that really does line up with the idea of RESTful routing because you're likely going to have a dashboard's controller show action that's showing the user's dashboard. So, it makes sense, you know, that show page is rendering a dashboard object.
STEPHANIE: Can we talk a little bit about things not to do, or maybe things that might be a little more questionable [laughs], and if you've seen them and how you felt about them?
JOËL: I think it is sometimes tricky to define your boundaries right in that sometimes you create a facade object that really is just...it doesn't really represent anything. It's just there to wrap around some other things. And sometimes that can be awkward. I think the dashboard works partly because it lines up so neatly with the sort of RESTful routing and thinking in terms of resources that you want to do at the controller layer.
But drawing boundaries incorrectly or just trying to throw everything in some kind of grab bag object can...it's not a magic bullet, right? You've got to put some thought into the data modeling, even when you are pulling the facade pattern.
STEPHANIE: Yeah, I think other things that I've seen before that could theoretically follow this rule maybe [laughs], you know, I'd love to hear your thoughts about it. When you start, you're like, oh, like, my controller action method does just, you know, set one instance variable. But it turns out that there's all these other instance variables that either through a hook or, like, in the parent controller or even in the view I've seen before, too [laughs]. And I'm just kind of curious if that kind of raises your eyebrow at all or if you've seen any good reasons for doing so.
JOËL: I think setting instance variables in a view would absolutely cause me to raise an eyebrow.
STEPHANIE: [laughs] Agreed.
JOËL: Generally, don't put logic in the view. I think that we definitely have in parent controllers; we'll set other instance variables for things like maybe a current user, right? That's how we store that state. And I think that is totally fine to have around. Typically, we don't access that instance variable directly. We're referencing some kind of helper method. But yeah, I would not consider that a violation of the rule.
I think another common one that might come up is when you have some kind of nested resource. And so, in your URL, you might have a nested resource where you're saying, "Oh, I'm looking at specifically this comment under this article or something like that." And then, you want to have access to both objects in the controller. So, I think that's a pretty common scenario where you might want to have both instance variables.
Something that I'm thinking about...this is not a fully formed thought, so I'm curious about your opinions here. Is there an interesting distinction between variables in code that you want to use within a controller versus variables that you want to be accessible from a view? Because instance variables in a controller are kind of overloaded. They're a way of having state in a controller, but they're also a way of passing data into a view. And so, that sort of dual purpose there maybe causes them to be a little bit trickier to reason about than instance variables in a random Ruby object. What do you think?
STEPHANIE: Yeah, I was actually having the same thought as you were going there, which is that it is kind of interesting that the view, you know, is that level of what you want to display to your user. But it can have access to, like, whatever you put in the controller [laughs], and that is...and, you know, in some ways, it's like, that connection needs to happen somewhere, right? And it's here. But I think that can definitely be abused sometimes, too.
So, this, you know, fourth rule that we're talking about really has to do with a more traditional Rails app. But, again, with the complexity of web apps in 2023 [chuckles], you know, we also see Rails used just as an API a lot with a separate front-end framework. And your controller is rendering some JSON, which I think has that harder boundary between what is the data that the server is involved with and what we want to send to our client. And I'm curious if you have any thoughts about how this rule applies in that situation.
JOËL: I think I tend to see not really any difference there. If I'm building an API, typically, I'm trying to do so in a pretty RESTful manner. Maybe I'm doing a GraphQL API, and things might be different for that. But for a traditional REST API, yeah, typically, you're fetching one resource or some sort of compound resource, in which case, you're representing that with a facade object.
And yep, you can generally get away, I think, with a single instance variable with, you know, a few exceptions around maybe some extra context about maybe something like the current user, or a parent object, or something like that. I guess the view is really you're using a different mechanism for rendering JSON, and there are a bunch out there that the community uses. I think I don't really see a difference between rendering to HTML versus rendering to JSON, or XML, or whatever. How about you?
STEPHANIE: That's a good point. I think I'm with you where the rule still applies. But I have also seen things get really loosey-goosey [laughs] when we decide we're rendering JSON, and now we're suddenly putting the instance variables into a hash along with other stuff.
But what you said was interesting about, like, sometimes you do need that extra context, right? And, like, figuring out what the best way to package that requires a bit of, like, sustained thought, I think, because it can, you know, be really easy to be like, oh well, this is the one interface that I have to get data from the server. So, if I just sneak this in here [laughs], what's the matter? But yeah, I think, you know, that's probably why rules like this exist [laughs] to help provide some guardrails and make us think a little deeper about it.
JOËL: I think sometimes, as a community, we maybe exaggerate the differences between, like, RESTful HTML view and a RESTful JSON API. I tend to think of them as more or less the same. We just have, you know, a different representation the V layer of our MVC framework. Everything else still kind of lines up.
STEPHANIE: Yeah, that's a really good point. I actually hadn't thought about it that way. Because I think maybe I have been influenced by the world of GraphQL [laughs] a little bit, or it's kind of hard to have a foot in both worlds, where you maybe have to context switch a little bit about, like, the paradigms, and then you find them influencing you in different ways. Because I have seen sometimes, like, what maybe initially were meant to be traditional more, like, RESTful JSON APIs kind of start to turn into that, like, how do we get what we need from this endpoint?
JOËL: I'm curious how you feel in general about the facade pattern. Is that something that you've used, something that you like?
STEPHANIE: I think I would say that I don't actually reach for it, like, upfront, right? Usually, I'm still trying to maybe put some things in my models [laughs]. But I have used it before once; it kind of became clear that, like, a lot of the methods on the model had to do with more really server-side concerns. And I was, like, wanting to just pull out some presentational pieces. I think the hardest part with the facade pattern is naming. I have really struggled sometimes to think of, like, it's not quite the component that makes it up. So, what is it instead?
JOËL: Right. Right. I think, for me, sometimes the naming goes the other way around in that I'll start more to kind of, like, routing our resource level and try to think about, okay, this particular view of the data that I want to have, or this particular operation that I want to do, what am I actually dealing with? What is the resource here? So, maybe I'm viewing a dashboard. Or maybe what I'm doing is creating or destroying a subscription, even though those are not necessarily tables in the database. And once I have that underlying concept, then I can start creating an object that represents that, which might be a combination of multiple ActiveRecord models that represent tables.
STEPHANIE: Yeah. You're actually pointing out, like, a really great use case that we see a lot, I think, is when you start to have to reach for resources, you know, that are different ActiveRecord classes. And how do you combine them together to represent the idea that you want, you know, for your feature?
JOËL: I think it's more of, like, an outside-facing perspective rather than an inside-facing perspective. So, instead of looking at, hey, these are the set of ActiveRecord classes I have because these are my database tables, how can I, like, tack on to them to make this operation work? I'll sort of start almost from, like, a zoomed-out perspective, blank slate to say, "Hey, this is the kind of operation that I'm trying to do. What sort of resource am I dealing with ideally?"
And, you know, maybe the idea is, okay, I'm dealing with a dashboard. I'm trying to subscribe to something...a newsletter, so the idea is I'm creating a subscription. Then, from there, I can start looking at, okay, do I have the concept of a subscription in this application? Oh, I don't. There is no subscriptions table because that's not a thing that we track in our data mode. That's fine. But I probably need at least some kind of in-memory object to track the idea of a subscription, and then maybe from there, that grows. So, I'm kind of working from the problem towards the database rather than from the database out.
STEPHANIE: Yeah, I like that a lot. The outside-in phrase that you used really triggered something for me, which is being product engineers, right? Like, having a seat at the table when the feature is in that, like, ideation phase, I think is also really important because that's where you really learn what that like, abstraction is at the user level. And also, it could be a really good place to give your input if the feature is being designed in a way that doesn't really support the, you know, kind of quality of code and, like, separation that you would like. That's the part that I'm still working on and still learning how to do.
But sometimes, you know, it's, like, really critical to the job to, like, be in that room and be like, these designs; what are some places that we could extract it at that level even? And kind of, like, separate things out from there rather than having to deal with it [laughs] deep in your codebase.
JOËL: I think what I'm really kind of hearing and emphasizing in what you just said is the importance of not just writing code but being involved in the product and how that really enriches you because you know the problem domain. And that allows you to then write the code that you need at the different levels of the app to best model the situation you're working with.
So, we've kind of gone through all the rules and talked about them. I'm curious, though, for you, are these rules that you follow in your code? How closely do you adhere to this set of rules? Is this still something that's relevant to you in 2023 as much as it was to the authors of that blog post in 2013?
STEPHANIE: I have to say they're not ones that I have thought about on a daily basis, but after this conversation, maybe they will be. And I am kind of excited to maybe, like, bring this up to other people on my team and be like, "What do you think about these rules?" Just, like, revisiting them as a group or just, like, having that conversation. Because I think that's, you know, where I am most interested in is, like, is wondering how other people incorporate them into their work and hearing different opinions from the team. And I think there's a lot of, like, generative discussion that ultimately leads to better code as a result.
JOËL: I think for myself, I'm not following the rules directly. But a lot of my code ends up approximating those rules anyway because of other principles that I follow. So, in practice, while my code doesn't strictly follow those rules, it does look pretty close to that anyway.
STEPHANIE: I almost think this could be a great, you know, discussion for your team, too, like, if any listeners want to...not quite a book club but kind of an article club, if you will [laughs], and see how other people on your team feel about it. Because I think that's kind of where there is, like, a really sweet spot in terms of learning and development.
JOËL: On that note, shall we wrap up?
STEPHANIE: Let's wrap up. Show notes for this episode can be found at bikeshed.fm.
JOËL: This show has been produced and edited by Mandy Moore.
STEPHANIE: 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.
JOËL: If you have any feedback for this or any of our other episodes, you can reach us @_bikeshed, or you can reach me @joelquen on Twitter.
STEPHANIE: Or reach both of us at firstname.lastname@example.org via email.
JOËL: Thanks so much for listening to The Bike Shed, and we'll see you next week.
Did you know thoughtbot has a referral program? If you introduce us to someone looking for a design or development partner, we will compensate you if they decide to work with us.
More info on our website at tbot.io/referral. Or you can email us at email@example.com with any questions.Support The Bike Shed