Lessons for Building Resilient Codebases

Hey, everyone. Wow. I'm shocked with so many people here. I was joking, like, the biggest fear I have with a multitrack event is being in front of five people in the first row and speaking. But, yeah, thank you so much for joining this session.

Like I mentioned before, I'm coming from Romania, from a city called Cluj. I'm one of the organisers of JS Heroes. I'm not sure if anyone heard of JS Heroes or has been to JS Heroes. Nice. A few hands, cool. Yeah. Do come find me afterwards if you want to talk more about conferences and organising and community events. Happy to chat until the evening about that, if you want.

Today I'm here to talk from the role of product engineer at Code Sandbox. If you want to follow along the slides, they're already online on bit.ly. You can grab those later. There are a couple of references throughout the slides. You don't need to take pictures or anything.

I'm speaking from the experience of a product engineer and basically working at Code Sandbox for the past four years, working at previous companies in similar roles, and dealing with code bases, right? The problem with code bases is they degrade over time. This is just inevitable. What do I mean by resilient code bases? Let's talk a bit about why this is even a thing.

When you work in a product company, or you work in general at a mid-sized project, start-up, large-scale project, most of the time, the priority is going to be shifted around the features, the user needs, the business needs, not so much on the engineering side. Let's be honest, you don't have time every six months to rewrite everything or rethink the architecture or build whatever is the hottest framework nowadays.

This kept me thinking over the years. I started gathering this, you know, lessons from building these code bases. How do you ensure that these code bases stand this stress? Basically, if you take code, the code base that you have, over time, there are pressures that get applied on your code base, right? Those pressures can be team changes, people that have initially built the architecture maybe are not part of the team any more. You can have priorities shifting in the company where the code base maybe is not in a central role at this stage in time. You can have the product roadmap that has a lot of pressure again on the code base, features that you haven't even considered in the beginning when you wrote the first lines of code that now have become like the central part of your code base. The business can pivot to something else but you're still using some of the foundational work that you build at first. That gets more and more interesting with that.

Also, time-passing, like I said, code just degrades over time, maybe technical depth accumulates, that's inevitable, so how do you deal with this?

The problem is that the more you have all these different vectors of pressure on your code, the more likely the code base will crumble or become that legacy thing that everyone hates to go back to and have to maintain something on it. The objective here is to talk about how can you make this better? How can you build this protective layer around the code that you write or what are the things that you can do to just make sure that over time, you know, code bases keep this resilience and survive these kind of external pressures?

Lesson number one is to accept imperfection, and what I mean by that is that perfect, in our case, is the enemy of good, because you have to do a good enough job. Lesson number two is related to collocation. Collocation helps both when writing the code and when reading the code.

And a couple of examples here. I'm going to jump straight into code. I'm going to show a couple of things from production code, so, like, you know, it's not like most of these things are not faked out or anything like that. I just want to show you a couple of examples.

It doesn't really matter, like, the code as much, I just want to highlight things that I did over the past years or with it as a team to, you know, things where we accepted things that are not perfect, right?

In this case, I recently added this fetch to an end point to fetch, like, templates for the code sandbox editor when you want to create something new. And this is not going through our regular, you know, API abstraction layer that goes to the backend, sets headers, sets authentication and so on. This is just a fetch inline. And the decision to make it here is that we don't really want to, you know, we didn't want to expand the abstraction of the current API, so this is kind of not ideal. Of course, it's just written here in a function, but it works, and it's a one time thing, and it's a small imperfection that you accept, it's an exception to the whole architecture of the application, and, you know, you accept it and you move on.

Another example is when we introduced this idea of a draft, right? And draft comes over our permission system which has like a 0, 1, 2 possible values, levels of permission, draft is a special thing on the client side. So instead of going with changes all the way to the backend and to all the layers of the application, we started introducing these conditionals in the code to, you know, to work differently for drafts which were kind of like a very client concern. Again, doesn't matter, you don't need to understand the code, it's just the principle that an imperfect architecture model allows you to take reasonable shortcuts when needed, exceptions are tolerated but well documented when they happen, and a very important architecture must not stand in your way. If you need to build something, if you need to ship something fast, it's okay to take these exceptions, to take these shortcuts, and you don't have to fight the architecture or the constraints of your system to do that.

Lesson number two is related to collocation. I actually wrote an article about this if you want to read more about collocation. I wrote it especially from the perspective of how DevTools and frameworks handle collocation and how they help us with the writing phase of the code. I want to also quickly describe this as like what do I mean by writing and reading phase? So code as, you know, you take the life cycle of a code, it has a write phase where you go in and I don't know what this scroll bar looks like. Okay. It wasn't like that. You write a code and you push it on Git or something, right? This is the write phase. This is when, yeah, this is the write phase. On the read part, someone else comes in and reads that code, right? Someone else can come again and read that code, and you might come and read that code after a while, and we will see about that just in a few minutes.

So the idea is that collocation helps both when writing the code and when reading the code. When writing the code, you can think of how useful it is to have tools like in this case JSX and Tailwind, right? You're writing a piece of code. It's like you're doing handwriting and you're not lifting your hand, right? You're describing the semantics, you're describing the styling, you're describing the conditional logics based on which something gets rendered or not, and this is very low-level collocation and this is really helpful in the writing phase. You can think of it also as when you have already like a big chunk of code, like a big set of components, writing something new, adding a feature doesn't require you to go in multiple places and introduce multiple new files. You can put everything in there. On the read side, again, collocation just in small chunks helps a lot, but I also want to highlight something that I found very useful recently. When you have a bigger codebase that, again, scales over time, what I found useful is to not extract all your components in different files.

When you have a bigger codebase that, again, scales over time, what I found useful is to not extract all your components in different files. This is one of the problems with applications and with codebases as they grow, right? You tend to build each component, you have each component in a new file. In this case, for example, the header of the dashboard component here, again, the code is not important, it's just more like a concept here, so there's a header exported from this file, but this file also contains, actually you can see it here, contains another component called search input group. This sounds like the kind of component you want to extract away, right? But it is very specific to that header. It is used only once there, so the decision is that whenever this happens, you keep the components next to the parent component. Even though this file gets long, and I can show another example here where we have the pricing plans on the checkout page, and this is like a complex UI with all sorts of things. Again, there are tons of components here defined as you can see in the same file. What's important is that the file exports a single component. Everything else is kind of like details of the main component and is not abstracted away, and is not taken someplace to be reused later. This, again, coming back to the lesson is collocation in the sense that when you write the code, you write it in a single file as long as you keep the concern is the same. You're just building this new component, even if it's broken down into multiple components or maybe it has some utility functions.

From the read perspective, it's also super beneficial because anyone comes in, and when they know they have to change something on the plans page, they don't have to search for the actual component or smaller component that actually represents or actually has the change that they have to introduce. You might be looking at this and thinking, okay, is this a case against reusability? You shouldn't reuse too much code in codebases? The answer is yes and no. As always, it depends because lesson number three is that reusability is a double-edged sword. You tend to think that everything, like, the better you reuse stuff, the better you abstract away utilities and components, the better it is for the codebase in the long run. But I would argue that there's a good part and a bad part to reusability and you have to balance them. On the good part, you have things like abstracting away black box, you have deduplication, obviously you don't repeat yourself and you have separation of concerns when you do it right. On the bad axis, you have zombie code, right? Assuming that some of those smaller components are written in separate files, for some reason, the main file changes, it no longer uses one of the small components, but you don't have a direct correlation that, oh, I have to remove this.

Of course, there are tools that help you with that, but fundamentally, when you're thinking about making the change, you don't have to think where else is this thing used or something like that? You have unnecessary abstraction, like I mentioned with the example earlier, like the API thing. If you have a single exception to a kind of design or architecture, then it's better to make it an exception than to change the abstraction to support that exception. Finally, change propagation, which means once you make a change in a file, how many files actually depend on that or how many places, you know, if you have a piece of code that is reusable and you have to change it, then are you sure that in all the places where that thing is used, you're not introducing some bug or some issue, plus the fact that you have to go through a couple of files or a set of files to make a single change to the code? So, you're kind of dangling this slider whenever you have to think about reusability, right? How much do you want to reuse? How much do you want to duplicate? I found it useful to have your own framework for this and think of it as, okay, should I reuse this thing? Just a couple of questions that I like to ask about this. Will these things change together? Meaning that if the parent component changes, does it mean that I have to go in the child component as well and make a change? Or if the component changes, does the utility that computes something also have to change? Because if they change together, they might better stick together than have some sort of reusability or abstraction there. So, if you do decide to abstract something away, how often do you change that reusable code? Thinking about change propagation, right? The moment some piece of code that is reusable needs to change, there's a higher chance that you introduce some sort of bug or regression because of the number of places where that thing is used. And finally, it's very important for the read phase, do you need to understand the code that is reused? So, you write the code, you extract something in the utility, does the name of the utility give you enough information so that when someone else comes in and reads the code, or you come in after a while and read the code, do you know what's there or do you have to actually open that to figure out what's happening?

Lesson number four, speaking of understanding that code, is to leave traces behind. This is very interesting. I really like to think more about this.

We can make it. Lesson number four, speaking of understanding that code, is to leave traces behind. This is very interesting. I really like to think more about this. How do you manage this over time? Have you ever gone through a piece of code wondering what the hell is here? I don't know who wrote this. And then you put GitLens, and it says, it's you, 14 months ago. This is very common, and why this happens is, again, thinking of that read phase of the code, right? When you write the code, you write the code at a certain point of time, three months later, someone else comes in and reads the code, I swear to god, I don't know what the scroll bar is here. It's a browser thing. Three months later, you come and read the same code. Guess what? You from six months in the future is not the same as you today. You are looking at the code maybe with new eyes. You just forgot about some of the implementation details. It's very important to leave these traces behind for you and for your colleagues.

The most obvious traces that you can leave are comments. Everyone likes comments, hopefully. You don't consider that code is just self-explanatory. We have code that is very critical or sensitive, right? For example, like a branching code in a loading phase, right? This is, for example, the critical part of loading the project in our editor, right? Again, all the code snippets are from production, so, yeah. We write a ton of comments because we know any change here is very hard to test first because there's a lot of logic involved. Are you an anonymous user? Do you have permissions? Are you in a workspace? Are you looking at the right thing? Are you looking at the passing of all the parameters and so on? There are a ton of possibilities. We comment a lot on this kind of code. With comments, of course, you leave the traces for future you as well.

Next one is breaking down more complex algorithms in smaller steps. This goes a bit opposite with the thing we talked about, but in some cases, you do want to extract something like this. For example, remove panel from layout is a function we have when you remove the last tab of a panel, right, in a tabbed layout. This is done in two steps. First you remove the panel from the group and if that group has no panels left, then it needs to be removed as well. The algorithm is broken down. When you come back and read this, you know exactly what the code does because you have kind of like the instructions, like the top-level algorithm here.

Finally, my favourite thing to do lately has been to what I call hoisting conditionals. Whenever you have all those things where you say, oh, if something dot length is greater than three, whatever three may be, I find it very useful to always hoist that logic into some clearly-named variables at the top of components.

We really abuse this. Is team admin should apply sandbox limits? Even if it's a 50 character Boolean, it's still better because it explains to you further down the line when you read that code why that condition is applied there, why that code is conditioned by this thing. Imagine having to duplicate all the logics and all the Booleans everywhere in all the rendering.

To sum it up, leaving traces behind, comments, breaking the algorithms and hoisting the values for helping you and helping others understand the code better in the future.

Now, lesson number three is better strict than sorry. So, can anyone tell me what are the possible values of is pro here? What does it look like? It's a Boolean? Yeah? Okay. Nice. Thanks. You spoiled it. Yeah. It's a Boolean. Technically you look at it and say, of course, it's a Boolean, it's pro. So then what you do is say, oh, if the user is not pro, you show an upgrade banner. Let's see what happens. So, for a split second there, the banner shows and then it disappears and that is because is pro needs to be tested exactly for its value, which only when is pro is false explicitly only then the banner should show.

The problem is that is pro is Boolean or undefined and the underlying problem is that sometimes you might not even see this unless you use the sponsor of our talk. Sorry. I'm joking. Unless you use TypeScript. Because TypeScript gives you the power to say very explicitly, hey, this is a Boolean or an undefined. And I would take it another, yeah, sorry. I forgot about this. This is very important. TypeScript even doesn't tell you that it's a Boolean or undefined unless you use strict null checks. Anyone using strict null check in their codebase? Okay. It's a half, half thing. It's kind of hard to put it there once you don't have it from the beginning, but it's really important to be able to express the full extent of the values, right? And we're going one step forward and saying, okay, the return type of a hook is explicitly like this. It's either no data yet and then you strictly type everything is undefined, right? Or it has no subscription object and then you even type it as the actual value that you expect and then you type it with what you would normally put, like, the regular type there at the bottom. And this is super helpful, again, because you avoid any of these issues where, you know, you have flickers on the screen, undefined, null checks, and all that, and of course possible runtime errors if you don't use a strict null check. So, finally, the code should actually look like this, where you even test for is pro just to make sure that, you know, you're testing all the exceptions.

And then after line, it doesn't have a number there, but after the first conditional, basically, this pro is going to be exactly what you expect, true or false, because you tested out the outlier, which is, again, undefined, but it makes sense because it's undefined while data is being fetched in the initial phase.

So, to conclude better, strict and sorry, use TypeScript as strict as you can. Explicitly type all the states of your data. Don't forget about when it should be null, when it should be undefined. Handle all these possible states because this will save you a ton of errors in the future and weird flakiness in the application.

A quick recap over time. Accept imperfection. Colocation is king. Reusability is a double-edged sword. Leave traces behind, and better strict than sorry. These were my five lessons for building resilient code bases.

These were my five lessons for building resilient code bases. Thank you for joining.

Let's see, which one do we want to do first? All right, here. You showed an example with multiple components in one file. How do you feel about keeping them in separate files but in the same folder? That works, too. My problem with that is sometimes it's hard to jump between files. It depends on how skilled you are with the code editor as well. I found that sometimes for people it's easy to picture all the breakdown of a main component into a single file, but that works also with folders. The problem with folders is it invites you then to use things like index files which sometimes are the root of all evil in project structures, so I will be careful with that.

A lot of people have questions about keeping multiple functions in a file. Where did it go? I had one. A really good one. All right, here. When keeping several components in one file, how would you go about testing that file structure? That's a good question. I think that if components need to be tested, if the smaller components need to be tested for whatever reason, then probably they should be extracted away. But if they are just like a breakdown of the main component, then the test should be around the main component. It should be more like a high-level test than a very separate unit test for each snippet that you have there.

All right, thank you. So an imperfect architecture and being comfortable with that seems to depend on experienced developers. But if you have a team full of junior or less disciplined team, wouldn't that be a recipe for disaster? Yes and no. It does matter a lot to have the experience to know when something should be an exception and when it shouldn't. I think having some engineering guidelines for the team always helps. It always helped in my experience. Being able to say, okay, we always do it like this, right? For example, we only have a single component exported from a file. That should be a ground rule, right? Whether they're a junior or a senior should be able to read our engineering guidelines and say, okay, these are the rules, the ground rules. From here on, we experiment and if we find something in, for example, you find in a PR, someone at a junior, let's say, does, and you say, oh, wait, this is an exception, but it's a bit too much to tolerate. That's fine. The senior person, maybe, to review it and say, okay, let's not have this and maybe let's even write it in our guidelines that we shouldn't do this in order to scale properly the code base.

Yeah, and you mentioned guidelines. I want to follow up on that with this question.

What about proper naming conventions? Would that help, too? Yeah, that always helps. I think being as... Even though it sounds silly, a lot of the PR comments that I've seen in the past on multiple projects are, hey, shouldn't we name this better like this? Because naming things is hard. As good as we think we are with naming things, having more eyes on a Boolean, a function, a component, and having someone say, yeah, this is good, but why if we name it like this? In my mental model, it sounds like I would recognize it better in the future. So always have naming conventions, but never be too shy to suggest in PRs, I guess, better names if you find that something is better understood this way.

When you're having multiple components in one file, we're sticking to that problem. Won't the version control be more complex and end up causing nasty merge conflicts? Well, maybe the idea of multiple components, maybe people think that all those components are kind of like siblings, but again, this is more like a parent-child thing. It's not... Most of the times, you won't be... I mean, let's say you come to that example with the pricing plans. Let's say you have to change, you have to introduce a new line for each card. That will probably mean you have to do changes in three components, maybe. Whether they are in three files or in just three different lines in the same file, the git diff will look the same, right? I don't think that's a big difference between the two. Indeed, if a part of that file changes... I mean, basically, when you have to fundamentally... Or not fundamentally. When you have to slightly change something in one of those files, it's okay that it touches all the components in that file. If it would touch multiple files, then in my mind, then it becomes a bit trickier to handle all the versioning and all the possible conflicts with other changes coming from other people and from different files.

Maybe a real quick last question. You mentioned having comments that are great, but as the code evolves, won't it lead to dated knowledge? Are there better solutions? I did not find a better... It's always a problem. I agree. You have to be very careful about not leaving comments behind. You should treat comments as part of the code. And again, use PRs to say... Hey, if you've done this change, you've changed the limit of something, please update the comment to reflect that or anything like that. I don't think you can... I mean, you could probably in the future automate that with, I don't know, with AI or something, but for now, I think we're stuck with what we have.