On today’s episode, we discuss some tips to follow when starting a new code base. It can often feel like you are climbing Mount Everest with no path when you traversing through these new, unexplored territories. If you tackle them in a methodical, structured way it does not need to be overwhelming. There are many tools out there, you just need to know which will be most effective for a particular code base. We also dive into some of the tools that we have used in our own work and how effective they have been for us. Sometimes it takes only one tool to help you wade your way through all of the new information, while other times, you need to use a range of them. With all of these tools in your kit, you can not only make it to the top of the mountain, but you can even plant your flag at the summit.
Key Points From This Episode:
- Knowing what to ignore is as important as knowing what to pay attention to.
- One of the easiest, but most overlooked ways to get to know a new code base.
- Reading the code alone will not help you solve any potential problems there might be.
- Why a unit test is a helpful way of uncovering any problems.
- Before using a README, make sure to see when it was last updated.
- Some ways to find out how an application works.
- Useful tools for learning about a React code base.
- Some IDE tools that can assist in figuring out a new code base.
- An ERD, if it can be generated is also a good place to start.
- File directories also provide useful insight into the code base.
- How the RADS file and code coverage reports can provide insight too.
- And much more!
Transcript for Episode 130. Traversing Through New Code Bases
[0:00:01.9] MN: Hello and welcome to The Rabbit Hole, the definitive developer’s podcast in fantabulous Chelsea, Manhattan. I’m your host, Michael Nunez. Our co-host today.
[0:00:09.8] DA: Dave Anderson.
[0:00:10.8] MN: And our producer.
[0:00:12.0] WJ: William Jeffries.
[0:00:12.6] MN: Today, we’ll be talking about traversing through new code bases.
[0:00:16.0] DA: Going where no man has gone before. Well, I guess, people have gone before just look at [inaudible 00:00:21].
[0:00:22.2] MN: Blame will tell you, whose been there and who left it and what they did.
[0:00:27.7] DA: Why they did it hopefully.
[0:00:28.6] MN: Exactly. You have a huge – you have mount Everest of code base that you have to learn and there’s – how do you start? It’s just like, there’s no path, you just have to make it to the top of this code base mountain. We’ll be talking about some of the things, I guess tips that people should follow.
[0:00:43.7] DA: The mountain of monoliths or whatever the corresponding version of Microservices.
[0:00:49.2] MN: Trees in the forest.
[0:00:54.1] WJ: I think more important than knowing what to look for is knowing what to not look for. All of the things that you need to ignore. Because the code base is many times larger than you can realistically read. You're not going to read it.
[0:01:06.9] DA: That’s totally true, yeah. You have to accept uncertainty and make assumptions. I mean, you could be wrong, but I think that’s one of the things that establishes senior engineer, you just get better at making assumptions about how things work and how they don’t work.
[0:01:25.8] WJ: Yeah, you really have to – it’s like a trust fall, you just have to believe. Look, the method says that it gets the data. I’m not going to read the method.
[0:01:37.1] DA: Right.
[0:01:38.8] WJ: It will get some data probably, whatever, we’re moving on.
[0:01:42.7] DA: Probably a day, you know? Maybe there’s type annotations on the method and that’s great, that will help you. If there isn’t then you know, dynamic languages, you just got to like, “yes.”
[0:01:52.4] WJ: That’s a problem for future me.
[0:01:56.6] DA: Yeah, that’s true. I think generally, starting from a user experience like if it is a web app or a mobile app or what have you, how does the user actually interact with it? At the front, what does that look like? How do you actually operate this thing, what levers are there and –
[0:02:15.6] WJ: Yeah, I think this is a thing that engineers are really tempted to skip. Like a lot of the times we don’t even think of it. But the easiest, one of the most crucial things you can do to learn the code base is to use the app. From the user perspective, pretend that you actually need to buy a widget or whatever is the app is for and do the thing.
[0:02:34.4] MN: Become the user, as you are the developer.
[0:02:37.9] WJ: Yeah, because once you understand the domain, then some of the metaphors start to make sense and it’s like, “okay, well, that’s clearly why they have a coolant model is because you know, the coolant model is going to represent the coolant, it goes inside of the cars,” is what they’re saying or whatever.
[0:02:53.0] DA: Right, yeah. Sometimes you may not have like a shiny React single page app, front end or what have you. It may not be a website, it may be an entirely back end app, but there’s still some kind of surface area there that interacts with the world. It couldn’t be like ingesting a file and that file has some format or it could be like an API that consumes data or some queue that puts stuff where it needs to be. Because there’s some kind of like ingress.
[0:03:24.2] WJ: Yeah, I think that if you start reading code, it’s easy to end up focusing on the wrong things and then you start to think, “oh, the problem must be in this one section of the code base because that’s the code bases that I know about.”
[0:03:36.9] MN: Right.
[0:03:38.3] DA: Yeah, very few times have I ever like, just read all the code like I said, we’re in an application for a while where it’s like 3,000 lines. It was like, “okay, I can read all the code, that’s not so bad.” Take you a couple of hours or like generally get the idea of what’s’ going on. But you know, if you’re working on an app that has like more than 10 developers who have been working it for more than a year then forget about it, you’re done. You can’t start a chapter one, get to the end of that
[0:04:09.6] MN: When I’m entering a new code base, I tend to see what they unit tests are like, just so I can see what assertions are made given the objects and the classes that I’ll be dealing with from the front end as you guys mentioned, all the way down to like the database. Just like to see what this class is responsible for and how does it pass data from one object to another. I think the unit test definitely helped me out with that regard.
[0:04:37.0] WJ: To know how scared, you should be of changing it.
[0:04:38.8] MN: Yes. There’s little test that you know that there’s going to be some things that will be set in stone that you should not change or be very afraid of changing.
[0:04:49.5] DA: Yeah, I guess, I like testing also tells you, it’s a similar thing, it’s like, looking at the interface of the thing to understand how it goes, what goes in and what comes out. You know, understanding people’s coding styles and like what assumptions they make when they write a test, how willing are they to patch out random details of a system or is it just like all end to end functional capybara selenium tests or what have you.
[0:05:19.0] MN: Yeah, I think I do try to look at the unit test and then go up and [inaudible 00:05:24], integration and stuff like that and see what is revealed to me.
[0:05:28.3] WJ: Yeah, I think also looking at the dependencies like looking at your node modules or your requirements take to you, your GYM file or whatever, whatever dependency management file you have, just to see, “how many third-party libraries are we using, are they generally, what kinds of categories should they fall into?”
[0:05:46.4] DA: Like starting from I guess taking back to get to the entry point it’s like, “how do I start the application locally and what happens from there?” like starting from there, looking at what kind of scaffolding that’s going on to start it up, that’s super helpful too.
[0:06:01.3] WJ: Yeah, the README also, depending on how recently updated it was.
[0:06:05.3] MN: Yeah, I think we mentioned before in time, you see a README, see when it was last committed and updated because the README’s may lie to you.
[0:06:14.5] WJ: Yeah. That can send you down a deep rabbit hole.
[0:06:18.0] MN: Your read is like yeah, “it says I can do XY and Z.” No one’s touched that in a long time.
[0:06:24.0] DA: Right, the episode eight, according to my tattoos is inserting in your project where we talk about like more of the human side but you know, it’s something we touched on too.
[0:06:34.3] MN: Yeah, I think, I mean, we mentioned it in that episode and it’s safe to mention again, if you’re looking at a README that’s very old, then do it some justice and update it if necessary. Or if not, delete it so that no one goes down that rabbit hole like you did, when you accidentally read a README that was not updated.
[0:06:51.5] WJ: Only you can prevent README fires.
[0:06:53.2] DA: Yeah, exactly. Yeah, delete it. Let’s assume that we do have a web app or like a React app or what have you, what are some ways that we can figure out how that application works our like –
[0:07:06.5] WJ: One game that I sometimes play is like looking at the user interface and guessing what’s a component. “Where did people draw the boundaries?”
[0:07:14.0] MN: That is pretty fun actually. I look at websites like that from time to time. “Is it just the button or is it this entire thing, is it the banner? Is that the whole component that has all these little things?”
[0:07:25.8] DA: React app tools is a fascinating thing, that’s the whole different thing. Just going to random people’s sites and poking at them with the React app tools. Going to NY times. “Oh, hey. it’s React! Look at that!” AMC.com, “oh, it’s React too.” We’ll just poke at all the stuff, it’s great.
[0:07:42.0] MN: React Dev Tools is definitely the thing you should get to – if you’re debugging or learning about the React code base. The thing it’s like, pretty cool. I have it and I use it whenever I can if I’m on a React code base.
[0:07:55.1] WJ: Yeah, same for Redux.
[0:07:57.0] MN: Yeah, Redux is cool.
[0:07:57.9] DA: Yeah, it’s pretty awesome being able to see what data’s passed in and then what the DOM is that results from whatever inscrutable thing you might be looking at.
[0:08:10.1] WJ: Yeah, I think whatever [inaudible 00:08:11] infirmary you’re using like ember inspector, they’re all going to have some kind of a Chrome plugin that you can get that will help you sort of figure out what is going on. That’s a good place to start, if you're trying to get going on a new project. You probably don’t want to do it for the whole app, just whatever page you’re going to need to work on next.
[0:08:30.7] DA: Right, like starting with a magnifying glass and just looking. So, I like to look at the structure of the app through some component inspector, back tier and then open up that network tab in chrome dev tools, see what fires of when I hit refresh. And look at all the API calls like see what is collected and it’s like, “okay, those are my next points of entry,” like where I need to drill down into next.
So, you can hop from front end to back end and start digging into like you know what the parameters are and what their response payload is and –
[0:09:06.1] WJ: And like why are there so many 500s?
[0:09:09.9] MN: Yeah, that’s happening in production, you should go check that out right now. Your 500s are no good. Do you guys for Ruby and –
[0:09:17.8] DA: On that note. Just a quick thing. Either if there are like 500s or whatever that you might want to look and see if there’s like some kind of log. If the logs are being consumed, some input somewhere or if like, the exceptions are being captured and put into Rollbar or Sentry or whatever other random tool like those things are pretty great as well.
[0:09:38.7] MN: Yeah, I fail to think about that, like using logging to your advantage, it’s probably another way to see how the code base is taking a request from a user in that user flow as well through the logs.
[0:09:52.2] WJ: Yeah, I think also checking out the monitoring, if the app has monitoring which hopefully it does. Looking to see like if people have people setup dash boards, what do they care about? Somebody bothered to create a dashboard that measures the number of abandoned cars or whatever it is. “Okay, that’s important.”
[0:10:08.3] DA: Totally.
[0:10:08.9] MN: Are you guys, do you use like IDE’s? Do you find IDE’s helpful as a helpful tool and does your IDE help you when you're traversing through code bases? I find that using WebStorm for React can be a little difficult, but I like it for like RubyMine is pretty cool, definitely IntelliJ, I would use to help me kind of learn some of the methods if there are any Java docs or what not.
[0:10:33.0] WJ: JetBrains fan boy over here.
[0:10:34.4] MN: Yeah, love me – what do you use, Eclipse?
[0:10:37.4] DA: Yeah.
[0:10:38.8] MN: Eclipse? Get out of here.
[0:10:40.9] DA: Yeah, Conrad’s been talking to me too so I am also going to JetBrains plugins all over the plugs.
[0:10:46.5] MN: The client buys it for me so I don’t care. I just want to use it. I mean, what do you use? [inaudible 00:10:51]
[0:10:51.2] WJ: I always use V —. I mean if I am – yeah, whatever. Too cool for IDE’s. No, I use IDE’s and when I do it is usually JetBrains. I mean they’re the main game in town for IDE’s these days so.
[0:11:08.6] DA: Yeah not a sponsor but you know, they should add us in Twitter.
[0:11:14.0] MN: But yeah, I do find that the IDE helped in some regard in trying to figure out like being in a Java project it allows me to see like, “oh where else is this method being called and why would it be called here and there?” And then try to follow. It helps do navigate, do the navigationals as we mentioned before from user to database.
[0:11:32.3] DA: Yeah, I totally feel that and there are tools for VIM and other editors like Ctags that help you get that same relationships, right?
[0:11:45.2] WJ: Yeah, although Ctags is a pain to set up. It’s like constantly wrestling with Ctags.
[0:11:52.1] MN: Have you seen them in the wild Ctags?
[0:11:54.7] DA: I know a guy who had Ctags once.
[0:11:58.2] WJ: I got it working as interested and stay working.
[0:12:01.8] DA: It is a dream. I mean nothing is perfect especially with dynamic languages, but –
[0:12:07.8] WJ: Oh, another good place to look where I often start is with an ERD if you can generate an ERD.
[0:12:15.0] DA: Oh my gosh I was just going say that. Yeah, I don’t know if – IDE’s must have this ability. I haven’t –plumbed it, but I know for things like Django extension or I think it was called Django extension or Django management tools you can generate relationship diagram of all the models and that is super useful unless there are so many models that they are all like microscope. So many models that they have like microscopic in which case you may need to zoom in a little bit and look at it like one module and it is immediate adjacent relationships.
[0:12:52.5] WJ: Yeah and usually it is like all of – why do all of these models connect to this one model? Oh, because that one model is where all of the code is.
[0:13:02.6] DA: Yeah and actually for – I mean you know I’m talking about GraphQL. We got to talk about Graph QL.
[0:13:08.1] MN: You got to. This is not a podcast without talking about GraphQL.
[0:13:11.6] DA: Yeah, talking again. Getting that GraphQL money.
[0:13:12.8] MN: There you go.
[0:13:16.0] DA: Yeah, like GraphQL Voyager, great tool to get a ERD for the relationship of the types in your schema, which is very braggable because it is hard to get that kind of level of documentation that’s visual and dynamic and interactive with the rest.
[0:13:34.8] MN: I just searched am ERD for React and there is one –
[0:13:40.1] DA: Oh my gosh I need that.
[0:13:41.4] MN: Yeah, it is called the Repo organization is a project storm and the name of the app is react-diagrams. It has how many stars? It got 2,750 and they got pretty cool diagrams and stuff. I will put this in the shownotes for anyone who is doing the React stuff.
[0:13:58.2] DA: Oh, please hook me up. I was looking for something like that earlier today.
[0:14:00.9] MN: Well you guys mentioned ERD’s and I was like, “oh, let me see if there is one for React” and boom there you go. You have it ladies and gentleman, Project Storm.
[0:14:06.8] DA: It is funny when you try to Google for something and you don’t know the word for it. You just can’t get it, but then if you hit on that phrase like the ERD and React, two words you get it. I was Googling 10 words.
[0:14:20.4] WJ: What does it stand for again? Something relational diagram?
[0:14:21.8] DA: Entity?
[0:14:23.0] WJ: Entity relational diagram.
[0:14:24.1] MN: Entity relational diagram, I honestly have to go Google what it meant and then I was like, “oh ERD diagram tools, got the definition.” Put on React afterwards and bam, I got Project Storm. There you go.
[0:14:35.1] DA: Professional Googler, thank you.
[0:14:37.3] MN: That is what they pay me to do.
[0:14:37.4] WJ: That is all we do is search out for this.
[0:14:38.7] MN: Hey and that is a thing you should do if you are learning new code base to use Google and Stack Overflow to your advantage in things if you don’t quite understand.
[0:14:45.7] DA: Yeah that is fair.
[0:14:47.6] MN: UML is that a thing we’re still doing in 2019? UML diagrams?
[0:14:52.2] WJ: I don’t think anybody ever did UML diagrams accurately like I mean it is nice that somebody formalized all the syntax, but really people just draw pictures.
[0:15:00.5] DA: Yeah thank you [inaudible 00:15:01]. Yeah, I think they are like elements of clean visual communication about programming that you can like pull out from that, but like that level of structure is hard to replicate unless you are a machine that generates that.
[0:15:17.8] WJ: Right, yeah. I mean I am glad that someone invented it and if you are building an ERD diagram generator definitely you should UML. But I mean I have learned some of the symbols because it was useful for white boarding and then I was like, “nobody seems to understand any better or worse if I just make these symbols up,” so.
[0:15:39.5] MN: Stars many, many have the number one. I don’t know if people are still doing the double parallel lines and between the thing, no one is doing that. Just put one and a star that’s what you do. One-star arrows pointing directions, boxes, UML.
[0:15:55.1] DA: It is the blame entity diagram that’s the word.
[0:15:59.1] WJ: We are going to get so much hate mail for shitting on UML.
[0:16:03.0] MN: All the UML people that will come out.
[0:16:04.9] DA: Yeah, we will have a battle episode.
[0:16:06.8] MN: There you go, but drawing is definitely helpful, so I think it was mentioned in one of the previous episodes with the pragmatic folks that you know have no path open to write things in the user flow and make sure you document it as like a really interesting way to understand the path of the code that you are looking at.
[0:16:25.2] DA: Yeah and I think they did talk about that too not stressing out about the dots and the dashes and whatever like just make a mental model. And if you follow the rules then fine. Otherwise, don’t worry about it.
[0:16:38.8] WJ: Another thing that I think it can be helpful to look at is just the actual file, like the file structure like the directories. If you just opened up the tree structure like expand all and look and see where people have organized stuff. That can be helpful for later like where you’re like, “where would someone have put this CSS file that I need? Oh okay, I remember how it was categorized.” They are doing pods or whatever.
[0:17:03.1] MN: Right it is not just looking at the code like the lines of code will look at where the code is placed and understanding the file structure of the code to understand where you would put certain things. So, like if a component, if there is a change that need to be done in the header then chances are that you are probably like had a component that encapsulates all the header component, really the items in there.
[0:17:24.9] WJ: Yeah and like oh, they have a fixtures directory so there must be fixtures. So now I know that’s a thing in case I need them.
[0:17:32.9] DA: Right and you can tell like what is closely related and also what people will value from a folder structure. Like it is a very shallow tree and there is a bunch of stuff on it then you know they are fine with more granular folder structure versus having a lot of folders with just a few things in it like for example like organizing your components with one folder per component where you have the styles in the index.js and whatever or if you just take everything from the page and just put it in a folder and you know, let god sort it out, which is fine too.
[0:18:08.0] WJ: Right.
[0:18:08.5] DA: There’s no wrong answers.
[0:18:09.7] WJ: Some teams are sloppy; some teams are obnoxiously OCD.
[0:18:13.9] MN: You got to know what team you’re working in.
[0:18:15.7] DA: It’s all awful.
[0:18:18.2] WJ: I guess there’s an in between. I suppose you could also check the routes.
[0:18:22.8] DA: Yeah, your entry points in the back end like just taking stock of what the menu is, I guess.
[0:18:28.8] WJ: Yeah, if you just skim the RADS file real quick, that will give you a sense of a wet surface area, your back end has exposed to the front end, is it a lot of routes? Do they all relate to you know, like five basic concepts? What is that?
[0:18:42.7] DA: Do they seem restful? Is it like –
[0:18:45.9] WJ: Are they wakeful?
[0:18:49.3] DA: Is it an end point for – Is it a route for products and a route for stores or is it like a route for like stores with products? And like you know, products by store and there’s like update the product route and you know, is it, what philosophy do they have?
[0:19:09.7] WJ: Also, coverage if there’s a code coverage report that’s being generated or any other static analysis reports like if they have code climate going and checking and seeing like, this whole section of files has just a straight F’s.
[0:19:22.3] DA: There are a lot of fun tools out there for like static code analysis. That can be pretty fun.
[0:19:29.0] WJ: Yeah, I hear there will be dragons, stay away from the –
[0:19:32.0] MN: Land mines, don’t step in.
[0:19:34.9] DA: Cyclamate complexity. Off the charts.
[0:19:37.7] MN: Don’t edit a file in there, you’ll be asked to change it. Yeah, I think we discussed a whole bit of tools that we would use, given we are having to tackle, this mountain of code, do you think we would make it to the top? I think so. I think we would and I think you can too.
[0:19:58.5] DA: Plant that flag.
[0:19:59.9] MN: Yeah. You know, small commits will save the day and every day, you’ll learn more than you have yesterday and give yourself some time. That way, you’ll feel healthy in learning this new codebase, whether it’s a nice walk up the mountain or a steep climb.
[0:20:16.6] DA: Yeah, take a nap, you know? Chill out, let it sit.
[END OF INTERVIEW]
[0:20:20.7] MN: Follow us now on Twitter @radiofreerabbit so we can keep the conversation going. Like what you hear? Give us a five-star review and help developers like you find their way into The Rabbit Hole. And never miss an episode, subscribe now however you listen to your favorite podcast. On behalf of our producer extraordinaire, William Jeffries and my amazing co-host, Dave Anderson and me, your host, Michael Nunez, thanks for listening to The Rabbit Hole.
Links and Resources: