How to navigate huge codebases when you're new to them

Transcript is auto-generated and may contain errors.

Hey folks. Oh, I knocked my camera. What an awful start. There we go. We're going to go to the experience dev subreddit. This one is about uh navigating and learning a a new code base that's large uh that you're new to and sort of like uh for someone who has, you know, not a lot of experience doing this kind of thing. And to be honest, I'm not sure if uh if that part actually matters. Uh whether it's your first time having to do it or your latest. I think the difference is that there's probably just your own tips and techniques and things that you kind of learn along the way uh to build on top of. But that's the context this person is asking how to do that because they they don't have experience.

Um, so with that said, as I start talking through this, it'd be awesome if you have your own lived experiences through this or thoughts on this, uh, share it in the comments cuz, uh, obviously as I talk through it, it's going to be my own perspective and I will try to think outside of the box a little bit, but I'm only one person and, you know, if you have different experiences, sharing that I think is is definitely helpful. So please do um yeah maybe let's just jump into it. So again the context for this person is they are more junior newer to a code base. They said it's not it's not big tech but uh they said it's still like you know from their without sharing where it is or whatever just like it's a not like a tiny company and the code base is is really large and big enough where they're like I just don't know how to understand it all where to get started.

And the other concern they have is that uh they're they're going to be introducing uh debt, right? They're like, I don't think that I can slow down enough to learn the code base. So basically, as I contribute to it, especially using AI, like I feel like I'm just going to be adding depth. And I think that's like a totally I mean I think that's a totally fair concern. I think it's a good um observation to kind of pause on and say, "Hey, like wait a second, like is there maybe a better way than what I'm doing right now?" Cuz it seems like it, you know, without some course correction, this could be not so good. So, um what are some different strategies for this kind of thing? I think the the one thing that comes to mind, some truck just blew through this intersection and there's I'm going to be following them, I guess, but there's something wrong with the trailer.

There's like stuff flying out of this trailer. Um, I guess we'll see in just a moment. Um, the way that I like to think about this kind of thing is some framing for uh just like how do you start understanding things in general that are uh that are a big problem space. And this is always going to come back to some form of breaking down the problem into smaller pieces. Oh, this guy is uh probably going to cause an accident of some sort. So when it comes to breaking down problems into smaller pieces, this is really just because I mean it's impossible or maybe very difficult for for anyone to try and take on something that is like you know so incomprehensibly big and just you know boil the ocean so to speak to to try understanding it all at once. So when it comes to code bases, for me that approach comes down to like uh different like what I call zoom levels.

So I like thinking about uh code bases in terms of like uh you know different different systems, different uh like block diagrams work really well for me. But uh I don't mean necessarily like I don't know like hyper specifically must be UML diagrams like show me your class connections and things like that. like I actually don't give a It's more about uh super high level. If you were to zoom out all the way from your codebase, can you talk to me about the codebase in terms of like some of the the big pieces that talk together, right? And and how they communicate and why. And that could be from the perspective of like I'm just going to make up an example like we have um we have some software that uh you know there is I'm going to talk about just like let's make up a an an app right so in our codebase there is a mobile app and there's actually a backend server and they're actually in the same repository.

Okay. So, uh they're completely different aspects of a system. And so that's important to call out because if I start talking about accessing a database, like what what is accessing a database, right? So this entire picture for me might start with like literally two huge rectangles like one is a an app on a phone and one is uh some service that's going to be running in a back end. And then just literally talking at a super high level like what what is this backend service, right? Okay, so we have this backend service. Yes, it runs in uh it runs in Azure. Okay, cool. Um and then it connects out to a database. So like just knowing that there's a database. Is that database also in Azure? Yes. Okay. And we have a mobile phone app. That's this other huge uh box off to the side. Cool.

Like is that like what language is that in? What platform is that for? and just getting a super highlevel understanding of some of the different pieces, right? And you, you know, maybe this is a bad example that's not resonating for you. So, let's say I have just a desktop application that you can download off the internet and install, right? Okay. So, it's one program, so one big box. Is there any storage for this? Okay. There's there is a uh local storage where we have a little bit of a cache database. And then all of your users information is stored in the cloud. So, um, no service for it, but it's just a database that is something that you connect out to to save. So, you know, I would have my big big box to show my app and then a couple of like, you know, maybe a small database icon or picture, whatever, and another one that's uh uh drawn out in the cloud.

And then so now I know at least I have some app couple of different storage things and then like from there what else is there? Is there some other third party service it connects to? Like maybe we could draw a little picture for that. Uh but just understanding like okay now I have this app and like are there is it like a layered architecture? So maybe you could say like in our app we have basically things broken down into like some of the UI code there is there is some you know explicitly broken out uh data access layer and then some other stuff in the middle but like without getting into the details of all of that just again at a super high level calling out these different areas. So my point is like I'm not prescribing exactly how much depth or exactly what specific things to call out.

My point is that I need to start with something super high level completely zoomed out and then now I have at least some frame of like what if we were zoom out all the way what things are we even talking about right to me it doesn't matter like what class name or like if you like specifically what framework necessarily is being used I might not even care what language maybe maybe at the high level if you're like, "Hey, look, our system actually has like some some pieces built in C and Rust and C++." Like, yeah, maybe you could say those are three separate entirely separate like parts of this system, but maybe just to make this up, maybe there's a Rust component that's like just a very small little very specific implementation of something and that's not even relevant to bring up when we're zoomed out all the way.

So the point is that having that sort of level of zoom for me is really important. Um I'm going to pause there for a second because the you know the evolution of that is like different levels of zoom. But you might be saying well Nick how do I even get that? Great like zoom levels make sense but like what what does that um for me historically this has been a human. So being able to talk to someone else on the team getting on boarded and being like, "Hey, you've worked on this. Can you show me? Can you talk to me about this kind of thing, right? And when I've been in the position where it's a codebase I'm super familiar with, this is how I start to teach it." Just like, let me just give you a highlevel overview of some of the different, you know, major areas.

Not enough that you're like going to be able to go find a class and know exactly where what lines of code to touch. Like not at all, but just like to start giving you a mental model to wrap your head around. And I find it works well for others and I find it works well for me, but I'm not saying it's a perfect solution. But yes, this has been with a person. Now, what's really cool and I actually don't have experience with this. This is me trying to think outside of my own uh lived experiences is like I think there are tons of AI tools now that uh try to do things like visualizing code bases and stuff like that. I have not personally used any of them. Uh I think that it's worth exploring. I definitely think that they're they're capable of doing you know what I'm describing.

I think my biggest concern or I guess two things would be like one is it accurate. That's always going to be the tricky part. Um, I think, you know, even as good as some of the models are now, uh, I think I think it's still like a, you know, trust but verify kind of thing because if you, if you go long enough, you'll realize like you're probably trusting an LLM when you shouldn't be and it's confidently telling you things and you're confidently believing it. So, trust, but verify. And then the other part is like I don't know like can I can I get the right uh what's the word I want to say like the right granularity of things to focus on. So that might be something else. Like I just don't know and I don't have experience using the tools. But I think there are lots of things that are are promising this kind of stuff to try helping people navigate code bases.

And the cool thing about that is I think some of them are like more visual. I think some of them are more like uh maybe trying to be more formal with like UML diagrams. I think some of them are interactive. Some of them might be more descriptive, but there are lots of options that are are coming about. So, I do think that that's a space that will continue to evolve, which is super cool. Um, I think that's very exciting. I think that's promising for more people that are uh finding themselves in positions where they're like, I'm going to have to learn a codebase. So, I would definitely encourage you to research things like this and try them out for sure. I just, you know, I'm not in a position where I can recommend ones I've used or anything cuz I haven't. Uh, but I I do think there are options for that.

It's also worth mentioning that you might maybe that sounds overwhelming. Uh, I have worked with people that are certainly not experts in in building stuff like this, uh, but have kind of whipped up their own little versions of it. And I think they've like we've seen in like hackathons and they've worked, you know, I think at least reasonably well to to paint a picture. Um, which is cool, right? Like so basically just talking with Copilot or Claude, whatever you want to use, and um and basically getting it to navigate a codebase. And the cool part about when they built it themselves is they can they can figure out like how do I want this explained for me, right? So someone was using uh like highle flowcharts to see like how different parts of the system connect. But uh I guess one more thing to call out is like when you're not the expert, when I said trust but verify, like how do you verify if you aren't the expert that knows the pieces?

Like can you actually verify if it's right? So that makes it kind of tricky. Anyway, I think there's some really cool options and it's I think only going to get better when we start going from there and talking about like zoom levels. Um I think depending on the size of the codebase uh it's uh and the size of the codebase and the work that you're trying to do uh it may not make sense to just keep going from this really far zoom and just keep like you know next level next level next level for me as an engineering manager not actively working in a codebase now that continues to be the pattern that works well for me because I rarely ever need to know specifically where to find lines of code. It's not it's just simply not beneficial for my job. Right?

If you told me this class name like has this method with these uh specific lines of code or whatever, even like knowing a method name probably not almost ever going to be helpful for me in my role. Uh for you it might be a lot more helpful. And depending on what parts of a code base or system uh are more heavily touched, exercised, right? For example, I know just from what it's been roughly two and a half years on the team I'm currently on, I know there is a particular uh module in a particular one of our services that performs a particular uh type of work. We're a routing platform. And so I know that there is uh a method that has a particular name that does some type of work. Do I know exactly what class it's in? No. Do I know exactly what the sort of algorithm or step by step is in there?

No. But I know what it's responsible for because it is a really um sort of core part to uh to some logic that has to run. And so I know that if we're talking about certain things, I'm like, this thing is probably coming up there. And it's enough that if I needed to go look up information without knowing uh the exact class necessarily or um the exact details of it, I could at least go ask co-pilot, go find go find this thing because I know it enough by name and what its responsibility is, right? But that's like that's like one thing and for you it might be very different. So my point here is that it in some cases continuing to zoom in uh just you know from the farthest zoom and keep going into more and more layers may not be super helpful because you might say well the system's so big if I keep doing that like at some point it's not super helpful.

So it might be get this highle zoom and then like the feature you're doing is like some some functionality in the at the data access layer for this app that you're building. So you have to touch some SQL queries or some entity framework or something else that's touching the database or interacting that way. Cool. Okay. So maybe you start with that highle zoom and for the feature you're building you have to zoom in on some part of the data access layer to to understand that more. So, uh, you zoom in at an area around that. Again, this could be using AI to try saying like, can you tell me how we interact with the database? Uh, asking someone, can you tell me what our data access layer looks like and where to find it? But getting uh starting to paint a picture of that piece more zoomed in.

And again, it might not be tell me every single query I have to have them memorized. I need an inventory of all of them. Um maybe for the work you're doing that is important, right? But my point is that you as a software engineer working in the codebase on a particular feature may need to zoom in more specifically. Um I'll go buddy. Thanks. Uh and so I think the way that I think about this is just these different levels of Zoom, but I always start at the highest level just to get introduced to the the idea. And then depending on what you're doing, having to zoom in a little bit more. And I think what's interesting too is if you're working in a codebase and so you did some of the data access layer stuff for uh for one of your work items. Oh man, not good.

Not good. Too tight of a turn. We did it. Cool. uh the next thing you're doing might be maybe not the data access layer and something else. And so you might get little pockets where you start understanding more specific parts and that might be a good opportunity to say cool like I'm seeing these pieces uh in their individual parts but like how do we how do we start seeing it more come together? That might be a good opportunity where you say cool I need like a different level of zoom that shows me these pieces working together. My point with all of this and it's probably been super redundant and I apologize is like the for me the mental model is very much trying to understand things at different um levels of depth. That's how my brain works.

Uh, I find that's it makes things easier to to reason about and rationalize because depending on the conversation I'm having um with like who I'm having it with, what we're trying to design, what we're focusing on, being able to talk about systems at different, you know, levels of granularity works very well for me. So, um, how you accomplish all of that, I think, can look different and will work differently depending on who you are and how you learn these things. I mentioned, pardon me, some AI tooling that you could try exploring, asking people. Um I I don't know like I think the the most important thing that you're doing as you're like what this person was saying it's like if you're scared that you're you know touching too much or like you can't slow down and you're just introducing the wrong things like like you have you have tools that can help you with that.

The one tool that we've had before AI is other people. So instead of like rushing in and just blasting code, um talk to people, right? Like look, if you think that like I'm going to go do this feature this way, touch this stuff, like go have a conversation with someone ahead of time and say like here's the spots I'm thinking of touching. Um if you're purely just using AI to blast things into a code base, I agree. like you're probably in a position where especially if people are just blindly approving things like that's probably what's going to happen where it's a absolute mess. So ask people that's been a tool that's been around for quite a while. And the other thing is that you do have AI. So instead of just using AI to blast code in, use AI to ask it questions. Right?

If you say I need this thing implemented, a lot of the time if you just tell it the thing you want, it's not going to think critically enough about like what's the best way to do this? Can we touch as little code as possible? Like it's not going to have these constraints just built into the question. You ask it to go build something, it's going to go build it. And if you do this enough, you'll realize until they do something about changing models and other things, it's going to blast tons of code, like just whatever it needs to write to get it done, it's going to go blast it in. So if you're concerned that you're just going to keep doing this and who knows what's going to happen to like the state of the codebase, you're not going to learn it. when you're trying to introduce a feature and functionality and you're using AI, like challenge it about different ways to go implement it, literally upfront.

Don't just say go build it and be off to the races. Have this conversation about like tell me like five different ways that we could go build this. You know, it might give you two that are completely dumb and you would never do it. Great. But have the conversation about why those are dumb. Have the conversation about why the other ones are good. Ask it questions. Take the time to ask and explore and understand, not just blast coded. I'm going to be late for CrossFit. I got to go. So, bye-bye.