How to Read Code

How to read other people’s code? You will need good code-browsing skills to make sense of the code.

Start by gathering information about which problems the program should solve and which code style to adapt.

Don’t spend all your time figuring out how everything works at the beginning. Narrow things down to something you can actually process.

Step through behavior that concerns you with a debugger. The stack trace have a lot of information about how events are propogated in the application.

In Action

getting it into a “smart” IDE that can make sense of it

try to build and run it (preferably in a debugger)

  • Find Main, Reading “main”

Learn to Dig

git blame

You can use git blame on a file to get an author name, last modified date, and commit hash for every single line.

git log

Use git log to look at the commit history of the overall repo.

git log can also show you the history of a single file with the -p flag: git log -p index.js.

breakpoint

One method the community strongly suggests is to set out breakpoint on methods that triggers behaviours that concerns you. If changing a line of code causes unexpected changes on other places, put a breakpoint on that line, and see what happens. You have a lot of information on the runtime state once the breakpoint hits. Breakpoints stops the execution of the code on a certain line, and from there, you can see from the stacktrace how the code got there. Use the step into and step out functions to see what the different methods does and how events are propogated in the application. This will teach you something about the structure of the codebase.

Grepping

the search function in your IDE

Search for Key Words

Use your editor’s Find feature (or grep) to search the entire source tree for occurrences of words associated with what you want to know. For example, if you want to figure out how/where the program opens files, search for “open” or “file”. You may get zillions of hits, but that’s not a bad thing–a focused reading of the code will result.
Often-useful words for C/C++ programs are “main”, “abort”, “exit”, “catch”, “throw”, “fopen”, “creat”, “signal”, “alarm”, “socket”, “fork”, “select”. Other words are useful in other languages.

Code Review

Software development is a very collaborative work. No one can build a large or a significant software alone. Every software is built in a team. In a team, everyone contributes to shaping a project. End of the day, everyone’s contribution get merged and become a good piece of work which has a real value to the customers.

Besides doing the actual coding, there is another practice that every team these days does, which is, review each other’s code making observations, suggestions and learning from one other. This is a powerful tool for building knowledge of a code base, creating strong bonds in a team and improving code quality that leads to fewer bugs in the system, and happy customers.

Doing code review, you are forced to read someone else’s code in your team which ends up improving your code reading skill.

Things to Remember

Go Back in Time

Read the Specs

Think of Comments as Hints

Commenting your code is incredibly important, for yourself and for your peers reviewing your code.

Notice Style

Expect to Find Garbage

Don’t Get Lost

  • Where is this button?
  • What do the tests do?
  • The graphical layout
  • Runtime Investigation

Find one thing you know the code does, and trace those actions backward, starting at the end.

Let’s call those connected pieces of code a “chain of actions.”

Following input events

Rinse and repeat.

a body of code is designed to tackle one (or more) complex problems.

the more you can gain an understanding of how different parts of the code are connected, the more you’ll develop an understanding of the entire codebase, as a whole.

the more (good) code you see, the easier it becomes to read and understand all code, and the faster you can do so.

“high quality examples of expertise” = good code

exposure to high quantity, high quality examples of expertise is one of the two main factors that dictate how quickly and effectively people learn new skills. – Badass: Making Users Awesome, Kathy Sierra

The more you watch (or listen) to expert examples, the better you can become. The less exposure you have to experts or results of expert work, the less likely you are to develop expert skills.

the longer you’re programming — and thus the more code samples you see, of all different kinds — the easier it gets to understand other people’s code. And the faster you’re able to do it.

Reading a class

Before reading the implementation of a class, however, I recommend you study its interface.

The public functions will most likely be the command interface for your class.

Retelling or Rubber Ducking

Use/know tools

There are plenty of tools out there for reading and exploring source code that can help to visualize code. For example – IntelliJIdea has really a great capability of navigating source code where you can search by words, part of a word or even abbreviation. You should learn the keyboard shortcuts as well. Navigating source code with the mouse can be pretty boring and slow where working with the keyboard shortcuts can be faster. You can jump from one part of the source code to another quickly.

There is another great software to read code, called Sourcegraph, which was created by two Stanford grads, Quinn Slack and Beyang Liu, who, after spending hours hunting through the poorly documented code, decided to build a tool to help them better reading and understanding the code.

Know the language/conventions

Read the best practices/design patterns

Temporary Refactoring

heuristics

Code is not like a novel

if you insist on understanding each and every thing before you understand the next, you will be lost for sure.

Let the machine help

Take the time to learn and use the stepper, trace, inspecting and browsing tools.

Many important relations in a program are non-sequential, and there are tools that will help you find what to look at next.

Start with an example

Don’t try to understand what all the code does at once. Instead, start with a specific example, representative of what a new user might try in his or her first session with the program, or an example from the manual primer.
Set yourself the task of learning just how that particular example works. Ignore everything else that doesn’t pertain to that example.

Go just as deep as you have to do to understand it, no deeper. Treat everything else as a black box. Learn about how it works later.

Become familiar with the user interface from a user’s perspective. For each user-visible action or object, ask: “Where is that implemented”?

Have a specific goal in mind when you work. Experiment with small changes and extensions to the code to test your understanding.

If it ain’t broke, fix it

The best attitude to take is to pretend you are debugging the code, even if there is nothing wrong with it. The same tools that are used for debugging the code will be helpful in getting you to understand it in the first place. Even if you aren’t looking for bugs now, if you plan on using, extending or modifying the code, you soon will be.

Tools

  • Jump to function definition
  • Step the code
  • Guess function names
  • Trace functions
  • Inspect the application’s data structures

RTFM

When all else fails, read the documentation.

another invaluable tool is stored inside your browser: the Developer tools. Knowing how to use the developer tools correctly and effectively can help you quickly locate the source of problems with styling these sections.

localized JavaScript console, where you can test out code separately from your programs.

Start with what you do know

find one thing you know the code does, and trace those actions backward, starting at the end.

Believe that you know what you’re looking at

For ultimately effective searching, you’ll want to use something like “language_name function_name” in your Google search, rather than just the function name, as they can be repetitive across multiple coding languages.

In the long run, expose yourself to high-quality code

By exposing yourself to well-written code made by experienced programmers, you are subconsciously taking in the methodology they follow, as well as their best practices.

If you read poorly-written, non-semantic code, you will likely emulate the same when writing your own. And yes, although we all start writing garbage code, our ultimate goal is to move on from that point as quickly as possible!

Try watching live-streamed programming (or pair programming with a peer)

it’s one of the best ways to watch the coding process from start to finish in real time, and ask questions as you encounter them. Watching other people program in real time also gives you insight into other people’s coding processes, and helps you develop good habits, regardless of whether or not they are a master themselves.

For an excellent resource on the front end (HTML, CSS, JavaScript), try perusing Codepen. Free, and very user-friendly, many front-end developers use this site as a sandbox.

On the back end, I recommend you sign up for GitHub and start digging into some of the most popular repositories. You can view a file from right within your browser, and if you wish to improve on the code, you can edit it in your own forked version and create a “pull request”. If the author likes your improvements, they may choose to implement them into their programs!

Find the high-level logic

Starting with the program’s entry point (e.g. main() in C/C++/Java), find out how the program initializes itself, does its thing, and then terminates.

Basically, skimmed through the whole project and gain a primary idea and then ask a question to yourself where do you want to focus, which part you want to read first.

Draw Some Flowcharts

Yes, we all know flowcharts are a horrible design tool, but they can be useful when analyzing program flow. You can’t keep all that information in your head, so draw some flowcharts or state diagrams while you are reading. Make sure you account for both sides of a two-way branch, and all branches of multi-way branches.

Examine Library Calls

Leverage the Power of Code Comprehension Tools

Some techniques available with a good text search tool, or better yet a tool that can analyze the source and find references and generate diagrams, allow the following questions to be answered, for object-oriented code:

  • Who calls this method?
  • Who implements this interface or subclasses this class?
  • What are this class’ superclasses?
  • Where are instances of this class created, held, and passed as arguments or returned?
  • What superclass methods does this class override?
  • Where might methods of this class be called polymorphically, i.e. through a base class or interface?

developing a “big picture” view of the code

reading and writing tests

Although testing is rare, it acts as a wonderful documentation tool, and is a good introduction to a new codebase.

Comment the Code

One of the best ways of reverse-engineering code you’re so unfamiliar with that you cannot even guess to comment is to derive HoareTriples for the code under scrutiny, and to compute a procedure’s WeakestPrecondition. Knowing the invariants of a procedure often gives valuable clues as to its intended purpose, thus letting you derive understanding from the code in a way that merely guessing from reading a number of poorly named procedure names simply cannot. Using this technique, you might even find bugs in the code, despite your lack of understanding thereof (I know this from experience!).

Clean Up the Code

Use Aspect Browser

Aspect Browser is a tool for viewing cross-cutting code aspects in large amounts of code. I find it indispensable for navigating unfamiliar code, as a kind of super-grep.

AspectBrowser for Eclipse

Resources