[afarrell]

How do you learn to read code without guidance and without getting lost? How do you keep your thoughts organized? At each step, how do you confidently decide where to go next?

———

I’d like you to take as given that I’m reasonably intelligent — I graduated from MIT and have been working as a software engineer for 6 years. Yet when I sit down to read https://github.com/cypress-io/cypress or https://github.com/webpack/webpack, I don’t know where to start or how to incrementally build up an understanding.

How can I learn how to read a project’s worth of code?

[nemild]

I emailed you. For everyone else, here’s a rough article I’m writing on reading code for my Notes to a Young Software Engineer series:

https://www.dropbox.com/s/q5mtxxk6bswkag6/Read%20Code.pdf?dl...

https://www.nemil.com/on-software-engineering/index.html

(The article has a few great HN threads on reading code; after all, there are lots of contexts where you need to read without working someone in person who’s been involved in that code)

[olikas]

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.

[afarrell]

> 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).

[dmux]

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).

[afarrell]

> “How to Read a Book”

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.

[opportune]

Well, I can definitely say I'm not an expert at it. Theoretically you might have more experience than me. But my job has me reading lots of open source code to try to learn about poorly documented APIs, so I've been kind of forced into it.

For me, I just try to follow the data and logic flow from beginning to where I want to do things. Though if I see something like a "strategy" pattern I ignore it unless I really need to know how it works; same goes for other code branches that seem unimportant to the greater program. You absolutely should use something like an IDE where you can move around quickly and get neat features like jumping to a class definition, find usages, etc. in case you get lost. It definitely takes time and isn't something you can just sit down and do for 8 hours straight. I generally can only look at code for 90 minutes before my eyes start glazing over and I need to take a break.

[e_carra]

I have the same problem. Every now and then I find some interesting OSS project I want to contribute or understand at a deeper level, but it's really hard to start doing something on it if there isn't an updated guide for contributors.

[sidcool]

Great question. This question itself is worth a separate thread.