I've spend my career reading code. I find it particularly difficult without guidance. I would recommend using some old school technology (pen/pencil and blank paper) and draw diagrams, write down every question and observation, notes. Others may recommend using some digital tool, but be mindful how much energy you spend organising your thoughts, drawing with a digital tool. If your goal is to understand a software, then don't waste time creating beautiful documentation first.
It is also important to have a clear goal. Let's say you want to understand how webpack starts up, or how it does a specific feature. Make this question your main concern and don't wander around. Don't try to understand everything at once. Divide and conquer.
It is also useful if you can ask questions, but please spend some time coming up with a theory first why things are the way they are. Formulate a hypothesis (e.g. "this piece is necessary because it handles an edge case", or "this piece of code looks uglier than the rest, is there a reason?") and try to prove it. If you can engage with the community, the better, but please don't outsource your "thinking efforts" to other project members. You can't learn how to reason about code, if you don't reason.
The most important one: be humble. Just because you would've solved a problem differently, it doesn't mean that the code is bad. Don't spend time judging the code. You are there to learn from others, so be open to other solutions. Whether it is a good or bad example is so difficult to judge... be patient and you will realise what kind of code is easy to understand. Once you have some idea, take that knowledge to your next project. This may take weeks/months/years depending on the project size.
> I would recommend using some old school technology (pen/pencil and blank paper) and draw diagrams, write down every question and observation, notes.
I have found paper and pencil to work best for my brain trying to manage attention while doing many tasks, so I take this to heart. That said, I think there is probably a tool I can use to be significantly more effective in organizing my thoughts—but probably one made of paper and pencil in the genre of the bullet journal.
If anyone knows of any techniques of organizing notes like this, I’d be grateful for some names that I can google. For now, I’m going to try experimenting with various ways of using flashcards (ALA record cards).
This is all great advice. Two things that have helped me in particular
(1) applying the "analytical reading" rules defined in "How to Read A Book" to a code base. One of those rules, as Olikas said, is formulating hypotheses and questions and "actively engaging" with a code base (or any text).
(2) Compare and contrast a similar project (i.e. using the same language and framework) to figure out whether the structure of the project in question is following a general layout or not (e.g. Maven projects in Java).
I’d seen that book a while ago but not picked it up. I’m now going to. Thanks!
> formulating hypotheses and questions
I think this reduces to “how do you keep those hypotheses organized?” which sounds kinda like the problem of “How do I write an outline?”
> Compare and contrast a similar project
This makes sense to me for web apps. Less so for a package manager.
I suppose that means the questions splits off into lots of domain-specific quesions like, “what should I pay attention to when reading a RESTful service?” “What should I pay attention to when reading a package manager?” Etc.
————
For a RESTful service, I would recommend first getting and idea of the core models from the API docs and then from reading structure.sql or models.py or whatever holds the relationships among tables. Draw an entity-relationship diagram on a big piece of paper of the important models.
Then, try and trace the path of a web request from the outside in through middlewares to the controller then to rendering and back out again.
It is also important to have a clear goal. Let's say you want to understand how webpack starts up, or how it does a specific feature. Make this question your main concern and don't wander around. Don't try to understand everything at once. Divide and conquer.
It is also useful if you can ask questions, but please spend some time coming up with a theory first why things are the way they are. Formulate a hypothesis (e.g. "this piece is necessary because it handles an edge case", or "this piece of code looks uglier than the rest, is there a reason?") and try to prove it. If you can engage with the community, the better, but please don't outsource your "thinking efforts" to other project members. You can't learn how to reason about code, if you don't reason.
The most important one: be humble. Just because you would've solved a problem differently, it doesn't mean that the code is bad. Don't spend time judging the code. You are there to learn from others, so be open to other solutions. Whether it is a good or bad example is so difficult to judge... be patient and you will realise what kind of code is easy to understand. Once you have some idea, take that knowledge to your next project. This may take weeks/months/years depending on the project size.