7 Tips To Navigate A COMPLETELY New Codebase

so these are three different strategies that are somewhat related in how you approach them but there's something common with all of them and I'm curious if you picked up on it all right so you're about to jump into a brand new project and this codebase has been around for several years it's pretty common for most of us we have absolutely no idea how to go navigate this thing because we're brand new to it so in this video I'm going to share with you some tips and strategies that I've used that I've helped other people with to be able to go navigate code bases that they have no experience in the strategies will help suggest how you can go approach this and then the tips will layer in and you can mix and match those with the different strategies before I dive in just a reminder to check that pin comment for a link for my free weekly software engineering newsletter okay we're going to start with the strategies and as I go through these strategies there's going to be something common with all of them and I want you to pay attention because I'm going to explain it after and we'll see if you got it right the first strategy is going to be starting at the top and what I mean by that is looking for the entry point of the the application that you're starting to look at and then trying to see if you can look through the code from the beginning so the entry point and then step through going through the call stack of the different methods that are there by following this you'll get to see what goes into the setup process for the application how are things initialized what's being initialized there's a lot of core things that usually get set up in the beginning and might give you some insight as to what's going to be happening later now this can be really effective for a linear application something that might be closer to a script or a workflow execution that's going to be happening line by line and not a whole lot of events or other signals that are coming into the application but what about other types of things like UI applications or even web services well for UI applications this might not be very useful it's going to be a little bit tricky once you get past the initial setup and you have the UI actually displayed to the user when the UI is present you're going to rely on things like events and user input that's going to dictate what happens next so following this approach gets kind of tricky because once you're set up you're waiting for those other events to kind of trigger the same process and once they happen so you get a user click you could go look at the event handlers and things like that to go follow the same type of approach but the reality is once you have some type of event like that you're going to have to wait for some other user input at some point to be able to repeat the entire process again with web services it's kind of similar but maybe not so bad because you can look at the routes that people are going to be hitting on your API when you look at these particular paths you can essentially treat them like an entry point for that particular thing that someone's trying to execute so whether it's a get or a post or some other type of method you can get that route and then step through line by line kind of going from the top to the bottom so maybe it's uh getting something from a database or putting something into a database you're looking how that execution happens and then looking at it bubble right back up to return some information to the user strategy number two is going to completely flip this on it head and we're going to skip looking at any code to begin with and just start with a really highle design instead of potentially having a very narrow lens and looking at some code what we're able to do is step back and have a really big picture of all the different parts of the system for me personally this is one of the most effective ways that I learn about new code bases and I would say in particular especially as a software engineering manager now and I'm not spending as much time or anytime at all in code bases programming at least at work this really gives me a picture of the the different parts and like I said because I'm not looking at actual code that makes a tremendous difference for me to have a mental model of what's going on now even as a software engineer when I was delivering code to code bases in my day job this was still really helpful for me because I'm visual a lot of the time when we're looking at code and trying to build up a mental model of what's Happening like that can be one one pathway for learning these things but having a visual representation as well in my opinion at least helps kind of get a a visual lined up with some type type of abstraction that you're already trying to build up mentally from looking at code so pairing these things together can be super helpful so my recommendation here is have someone get to a whiteboard or something else where they can draw out a really big picture for you with block diagrams again personally I don't think you have to get into like really hyper technical uml diagrams or things that are really specific just draw some shapes on the board get things drawn out so you can see how different systems connect maybe how different communication happens but treat it as a really high Lev way to look at the different parts of the system I think this strategy is one of the best ways to just not get bogged down in code and just start looking at aspects of the system to learn it at a high level and strategy 3 is going to be a little bit of a hybrid here but it's going to be focusing specifically on the core parts of the system so again ask someone for some information about what's really critical about this code base what are the top pieces of functionality that we're interested in and have them point out to you where that stuff is in the code you can get them to focus on some block diagrams for this type of stuff right so it's just the core pieces the core functionality that we're interested in and have them give you a rough idea what parts of the code base are doing that functionality especially if the code base is really big this can be very valuable because the reality is these critical areas of the code base for the core functionality are probably where the most churn is in the code it's likely where you're going to be spending some time either adding new features fixing bugs or working with other people on this part of the project so again best bang for your buck here for spending time trying to get ramped up is to focus on the core aspects and having someone point out to you where they are in the code base so these are three different strategies that are somewhat related in how you approach them but there's something common with all of them and I'm curious if you picked up on it well the answer is that with all of these we were starting with a really complex problem which is how do we go navigate this code base and if it's really big and you have no experience in it it's a big problem to go solve just on its own so instead of trying to fix that problem or find a solution just to that problem what we start doing is decomposing the problem right so instead of one really big problem we start scoping it down into smaller parts with the first approach it was well we don't care about everything we're going to start with the entry point and just start looking at it to get an understanding with the second strategy we were taking a really big system View and then not looking at the code so we're completely compartment mentalizing code and strictly looking at a high level Visual and the third approach what was really nice about that is we're instead of looking at the entire system we're decomposing it into smaller parts tell me where the critical pieces are tell me where that code is explain what that does and we're just going to start with that decomposing complex problems is a critical software engineering skill and I highly recommend you think about this because you can practice it and get better at it when you're faced with challenges that you have to come up up with solutions for instead of sitting there being blocked and going I have no idea how to go solve this you can start to think about smaller problems that you can go tackle as part of the bigger one think about any complex application that you've ever seen or used someone didn't sit there and just come up with you know the perfect database architecture the perfect microservice or monolithic solution like all of this stuff wasn't just figured out instantly to go solve this problem someone came up with a problem to go solve and then along the way they have to go solve these much smaller problems in much more detail and in turn those turn into their own big problems to go investigate but we have to be able to decompose the big thing to come up with solutions for the smaller parts okay now let's get into some tips that we can leverage alongside some of these strategies and again these strategies aren't the only way that you could have gone and approach this this is just ways that I've seen work well in some situations and I recommend trying them out the first tip is going to be about documentation So reading and writing or updating documentation if you haven't seen my previous video on this I'll put a link right up here you can go check that out and come right back but having documentation in place can be a luxury it's not always going to be there and a lot of the time if it is there it might be out of date which is why you probably want to go watch that video to see my recommendations there but if the documentation is there and it is up to date that's the point of it you can leverage that learning from your other teammates some historical information there and be able to navigate the code base based on what that documentation is suggesting it might be the thing that's pointing out the critical areas of the core functionality giving you some history about why things are a certain way so a lot of that Insight can be beneficial from documentation I highly recommend that even without that you start taking your own notes about what you're learning and exploring draw out pictures like get get a a view like that from your perspective about how the system works and the different components that you're reading about draw that all out and take all your notes in fact this is going to be extra helpful for one of the tips that's coming up and if that documentation isn't there and you are taking notes and you are drawing out some diagrams you could be the person that goes and creates that documentation to help out the next person or if that documentation is there but it's kind of crappy or out of date you can go update it you're helping out the next people to go through this and you're also resolidifying your understanding of the code Base by taking those notes drawing those diagrams and find find a way to explain that in documentation tip number two is all about getting our hands dirty you're going to run the application and debug it I often find that one of the best ways to learn things is just to jump into the deep end so if you're able to compile the code run it locally and again this is kind of tricky for me to say in a general sense because I mean you could be building any type of application or service and this video is going out to a wide audience I can't possibly know all the different variations of things but if you have the luxury of building and running locally based on what your system is or your code base that means that you can go step through things and check out the code if you have something like a UI application either if it's desktop based or a web app with a UI you can start to poke around and see if you can change some code and see if that's reflected in the user interface just really simple things like this can help you understand how data is transferred from different parts of the application to be able to show up in a user interface and part of that going to resolidify your understanding of what you believe you're reading it's a little bit trickier with things like web services but if you have something set up you could use say Postman or something else to be able to hit API endpoints and see what happens if you can provide the data that that route needs but the point is having a debugger in place with break points lets you execute different code paths and allows you the opportunity to see if your understanding is correct as you're going through the code tip number three is going to be asking questions so remember those notes I was telling you to make you're going to be taking notes in the code and the application you're looking at and drawing out diagrams take those things and go ask questions about them you want to reinforce your understanding by have someone verify what's going on you want to be able to leverage the knowledge and history that your team has you have people around you that understand this code base they can explain things to you and save you a lot of time now if you've taken notes and drawn out diagrams and done your best to get as far as you can when you go ask them questions people are going to appreciate app that if you've done absolutely nothing I can understand if you have hesitation asking questions because it's almost like hey look I haven't done anything but I need you to to kind of do it for me so take that first step take the notes if you're showing that to someone and being like here's what I think I've learned so far could you help validate it you're demonstrating to them that you've put in some amount of effort and I can't imagine that anyone's going to be you know upset to try and help you get a little bit further in your understanding the other thing about this is that I feel like people believe that that they're going to look dumb if they're asking questions but this is so far from the truth if you're asking questions to try and solidify your understanding there's nothing dumb about that think about it what looks more dumb asking questions to get some verification of your understanding or sitting in front of a code base for 6 months not being able to make any progress because you never asked a question in the first place now this tip does assume that there's a team in place for you to be able to ask questions too so I get it you might be a single person that's been put onto a project that would be unfortunate right if there's no previous team that you can go ask questions about but this happens right if you're in a position like this unfortunately this becomes a little bit challenging but what you can do is make notes of your assumptions the questions that you have and go back and re-evaluate them as your understanding improves so without the team in place to answer those for you your future self can come back and try to answer those questions and make sure that you're taking any assumptions and proving them or disproving them now tip number four also assumes there's a team in place so if there isn't this one's going to be pretty tricky to do so I'm sorry but I think this is one of the most effective ways that you can learn a code Base by layering this in with the other strategies we talked about earlier and that's going to be pairing up I think that when you can pair up with someone and have them navigate the different parts of the codebase the application that you're looking at this can be so valuable because like the other strategies we talked about they can really pinpoint the core areas that you should be looking at there's so many things that come up in conversations like this that you might not have exposure to otherwise and having someone do this for you can be super helpful but there's a bit of a trick to this that I want you to pay attention to if you're pairing up with someone I want you to think about them as a navigator I don't know if many people have seen rally car drivers but you have someone that's driving the car and someone that's navigating and it's pretty incredible so I recommend you go watch a video like this because they're driving at a crazy speed and the Navigator is simply just telling the driver what to do next and the driver is almost blindly just uh trusting what the Navigator is saying because they're going so fast it's almost like you don't have time to think except respond to your Navigator so you're not going to be going at quite a fast pace in a in a dangerous situation like this but with a navigator this person that's helping you try to get through the code base I want you to be The Driver and I want you to be the driver because it's going to help reinforce some muscle memory of being able to go through the code base if you don't believe me about this try it out both ways have someone do the driving and navigating and you'll sit there and you might go oh I think I'm getting this it's making sense and then when they leave you and you're on your own see how well you can navigate personally I feel like I've seen this enough times even for myself or other people have been navigating and driving when they're trying to show me something and it seems to make sense once they leave I go oh crap I don't really know what I'm doing so by being the driver and having someone navigate for you you can get used to exploring it could be even just like you're in your IDE like what keyboard shortcuts are you hitting like how do I jump from this class or this interface or this implementation they're like really trivial things that you might take for granted if someone else is doing them they might say oh go run this script and you can go see um how we access stuff in a database or other tools stuff like that but if you're the one doing it it just starts to become more comfortable right away so I do recommend you take this opportunity just to be practicing that and having someone navigate it might feel kind of slow and clunky but that's the learning process happening I like to think about it as having some training wheels in place and I think you should take advantage of that while you can that's going to wrap up this video where we talked about three different strategies and four different tips that you can layer on with those strategies they're not necessarily mutually exclusive and I think that if you look at the benefits and the pros and cons of what those strategies are and how they might apply to you you can mix and match them how you see fit one of the core things that I want you to take away from this video is that it's all about breaking down really complex problems into smaller more manageable ones and the other part that might have been a little bit layered in here is if you have a team I do want you to be asking questions to them this is something that people struggle with a lot and if you're a newer software developer having challenges trying to figure out how to ask questions to the more senior m I recommend you watch this video next thanks and I'll see you next time