Why yes I do love mining the internets for blog post ideas :)
This particular question is about learning a new codebase at work, but I think there’s plenty of stuff here that would carryover to learning the codebase of an opensource project you want to contribute to.
When you want to learn a new codebase, the very first thing you need to do is get it to build on your machine. Deliberately breaking things is an extremely useful tool when you want to understand a codebase, if you can’t even build the app you have no chance of figuring out if you broke it or not.
At work there should be another dev around who can sit down with you and help you get everything set up so you can compile, if you’re working on an opensource project you’re going to have to rely on docs, maybe a community chat like slack, gitter, etc, and sheer stubbornness.
Next you need to be able to run it or at least run the tests (if there are tests). This can be a lot more work than just getting the app to compile. For example, the app I work on at my own job compiles really easily but it won’t run unless you have all the environment variables set up correctly and the database and cache and everything installed. You’re probably going to want that coworker’s help here too. If you’re lucky your company has docs you can read and if you’re very lucky they’re even up to date, but at most places I’ve worked the development environment setup process was never written down, only passed down orally.
Quick aside: I’ve said this before, but if your company doesn’t have any docs, write them! Seriously, you’ll make things so much easier for the next dev, who might even be you. If your computer dies on you and you need to get setup again in a hurry, you’re going to be really grateful if you can follow the docs instead of desperately trying to remember how to do that one tricky bit.
Depending on how your app works you may also need help creating an account for yourself so you can actually log in and use it. Once you can build, run, and log in (if you need to), you can really start digging into the code.
What makes the most sense to me is starting from the UI and working my way in from there. It also really helps me to have a goal, like a bug to fix or a small feature to add. I get lost if I just sort of wander around a codebase trying to figure out how everything fits together, having a goal helps me focus.
It’s also totally okay to ask another dev for a quick overview of the app, having a bit of context can make it a lot easier to figure out how everything fits together. Customer documentation can be really helpful here. Sure, it won’t tell you which controller handles the data for the user details page, but it will tell you how to get there and what you can do there.
Eventually you’ve got to get in there and start looking around, though. I poke around the UI until I find a screen that looks like it could be related to the thing I want to do, then I copy some text from that screen (ideally something that looks distinctive) and search for it in the code. Most of the time this is helpful but sometimes the text you thought was distinctive really isn’t, you may have to search for a few different things before you find something that gets you useful results.
If the app is a webapp it often helps to open up the network tab in your browser dev tools and look at the calls the frontend makes to the server. If you’re not sure exactly which endpoint is actually getting called this can clear things right up. Don’t be afraid to add more logging either, just try to remember to clean it up when you’re done :) I do that all the time when I’m trying to figure out exactly what my app is up to. If you want to get fancy you may even be able to attach a debugger to your running application and step through the code one statement at a time. I have this irrational dislike of doing that (I find stepping through the code tedious and would rather just throw in another System.out.println), but if it works for you, great!
Once you find the right server calls it should be fairly simple to trace your way back through the code all the way to the database (or other data store) if you need to. I mostly work in Eclipse, so I’m working from the assumption I have good IDE support and can easily navigate the project once I decide where to start. If you aren’t using an IDE that makes it really easy to find the definition of a class or method, you’re just going to have to do a lot of searching.
IDEs can only do so much for you, though. When I’m trying to figure out a complicated part of the code I’ll sort of draw myself a map so I don’t get lost. That is, I’ll write down, either on paper or in a text file, exactly what calls the method I’m looking at, and what calls those methods, and what calls those methods until I’m clear on how everything fits together and where exactly that one bad parameter came from.
Like I said earlier, breaking stuff on purpose can be a great way to verify that you understand how the pieces fit together. Once you think you know where the problem is / where you should add your new feature, try commenting out the body of a method and seeing if things break the way you expect. If they do, great! If they don’t, hey at least you found out sooner rather than later that you were wrong about how it works. Another good way to break things is to give them bad data. I do that when I want to know if my request is even making it to the part of the code I’m interested in – if it doesn’t break the way I expected then I know I’m wrong about what the code is actually doing.
If one screen or endpoint or whatever just doesn’t make any sense to you, try another one! You may just need to see more of the app before things start coming together, or you may have just had the bad luck to stumble across an especially tricky part of the app. Keep trying, and ask for help if you need it, you’ll get it.
Speaking of asking for help: most developers hate doing it, but it really is okay to ask for help if you get stuck. Especially if you’re a junior, it takes practice to get good at finding your way around new codebases. Five minutes of explanation by someone who knows the code could save you hours of confusion and frustration. The faster you get up to speed on that new codebase, the more help you’ll be to your coworkers, so it’s actually in their best interests to interrupt them (after trying to figure it out on your own, of course) to ask for help.
One last tip: it takes months, literally multiple months, to really be productive at a new development job. If you feel stupid and useless, that’s a) not true, and b) totally normal. You would never tell a new hire that they’re an idiot for not instantly figuring out a new codebase, so try to be that nice to yourself, okay?