Summary | How to Read Unfamiliar Code by Josh Matthews
Summary of How to Read Unfamiliar Code
There's an under-viewed youTube video titled How to Read Unfamiliar Code by Josh Matthews which is one of the best resources I've found on the topic. Josh (at the time) is a platform developer for Mozilla. Here's a summary of what I've found helpful but I highly recommend watching the video along with the slides.
Get better at reading code
- Ability to read code comes from two things:
- Experience in reading unfamiliar code
- Confidence in which you approach reading code
- Overcoming lack of experience:
- Use context to make connections and assumption. For example start from a single UI screen.
- Overcoming lack of confidence:
- Organised confusion. Embrace your confusion with code, find ways to tame it. Think "I don't understand this, but that's ok because I can come back to it if needed."
- Instead of trying to focus on the entire code base, focus on a single feature and aggressively ignore everything else. To demonstrate, Josh goes through a single feature in Libre Office, which contains +7M lines of code in C++, Java and XML across 71K files.
Tools
- Pen and paper to log what he's doing and his thoughts
- Search tools like GREP
- Text editor (he doesn't really get into how to use an editor)
Iterative process
- Start with the UI, searching for specific UI keywords
- If there's no UI, exploratory searches of uncommon keywords attempting to find files/directories that may be interesting.
- Use code folding features (AS on Mac, collapse all: ctrl+shift+(-)), review version control history of a feature.
- Avoid doing as much as possible to be efficient in understanding what you're doing. Triage what code to look at, only look at what will be the most useful, aggressively ignore others.
- Inefficient is reading a file from top to bottom or starting from main() and following its path of execution.
- This is an iterative process. While iterating, keep a list of 2 things: 1) prioritised list of interesting items and 2) things you don't understand. In the second list, try not to go too far down a rabbit hole, want to go breadth-first vs depth-first initially.
- When looking at an interesting file, identify its relationships between other code, do some refactoring (e.g. setting public to private, renaming), set break points, to test assumptions.
- At some point, you'll have accomplished your goal of understand or will exhaust your list of items. If the latter, restart keyword search, start with a different related UI screen.
Resources
Video - https://youtu.be/wN4ZuGruiNwSlides - https://www.joshmatthews.net/cusec16/unfamiliar.html
Comments
Post a Comment