What are some of the techniques you use to read and understand a (mid to large) code base from someone else?. Say an open source library, framework, etc.
Do you write down anything? maybe by functionality, like methods, modules, components, files, maybe you use mind maps, or some other kind of abstraction? Or do you just straight up top-down read it and get it all in your head ;).
I found that this is sometimes not an easy task since keeping track of dependencies and/or async flow in complex applications is not a trivial thing. I personally have tried to abstract as much as possible and then go deeper into each part (as needed), but maybe you have a better method or way to achieve this.
The best way to understand a large app... is not try to understand it. You will have tasks. See where the entry point is and go from there. Try to understand as much as you need to get your job done. Refactor small things where is needed. If you are to spend a lot of time on that app, you will end up learning it. If not, any time spent on learning it, is wasted effort. Is more important to have a high level understanding of the business it solves. Have a look at the database and see what is in there, without wasting too much time on understanding all relationships. Is impossible to understand it all fast, and if you are in a large team, what you understand today, tomorrow may change. Don't try to rush your understanding. It will just come. You can do your job just fine if you take one step at a time and build the knowledge in time. Make sure you spend more time learning to clean the code and write clean code. Is a lot more value in that, and that will put value in any project. I bet a good programmer, with no understanding of a project, when going in it, it can make some good changes that help without any understanding of what the app is for.
It depends on why I need to read it. If I'm adding a third-party library with specific functionality to my code and it's not working quite right, I typically grep for terms I'm nearly positive will appear somewhere in the code specific to the functionality I'm interested in. Then I look at each one of those until I find what I want. If that doesn't work, I try to find the starting point in the code and follow it until I find what I need. This works for me most of the time.
I actually have to do this a lot at work. It would be very hard at first, but with practice it gets easier.
The "top-down read and get it all in your head" won't work. Unless you're a genius, you don't need to do it like this. Hell, I couldn't even do that to my own code if it's a mid/large project.
The hardest part is the start. You have to drop "the wall" between you and the code. That incontrolable "what the fuck" sentiment when you're reading the code. Try to put yourself in the writer's shoes and ask yourself "why would I do it like this?". When you begin to understand why things are the way they are, it gets easier to pick up the whole picture.
The codebase probably follows some patterns. Try to identify them. This is because, when people are adding code to something that is already there, there's some resistence to breaking the patterns that are already there. So people will end up writing code that is close to what's already there (or at least what they think is close).
Start small with small modifications, as demanded. Let your manager/boss know you will take some time there. You mustn't rush, or might endup messing something up.
That said, this is very hard and generally unpleasant work. So I wish you good luck (:
When I have to read and understand a mid to large size code base without the person who wrote it (getting them to explain would be the easiest solution), I do the following:
In my case, because I work in the Web, I do the following:
I keep updating that document as I discover new things, and extract it in HTML from orgmode files.
Well, in fact, I do what should have been done by the former devs, documentation...
But making it myself with the tools I am comfortable with is maybe what works best for me.
Hugo Mota
Code Hero
Josh Montgomery
web developer
my last couple of jobs I've had was exactly this, I took over a large code base from the previous developer because they left. I found that going over how the app is supposed to work in an overall general sense really helped, because then I could then go and look at that part of the code to see how it works. Doing that over and over again helped me make sense of the overall code.