(62) What is the best practice for reading source code?

What is the best practice for reading source code?

Ivan Sikiri?

15 upvotes by Ossama Nahdi, Boris Bralo, Jeffrey Hemphill, (more)

I have about 8 years of experience in competitive programming and 6 years of experience in software development. Reading the source code efficiently depends on what you want to read, and the depth of understanding you want to achieve. The most important factor in quick reading and understanding is your own base of previous knowledge on the subject being read. If you already know and are experienced with many coding patterns and algorithms, than it's much easier to understand well-written source code.

With that out of the way, here are some tips you might find useful:

• Learn to use your IDE. Syntax coloring goes without saying. Two most useful features in my opinion are "find all references of this class member/variable" and "go to definition of this function". So, just dive into the code. Name of some function is not very descriptive? Just go to definition (learn the keyboard shortcut) and have a quick look, then go back (learn the keyboard shortcut, or use the back button on your mouse). Need to track where a particular variable is being read/changed? Use "find all references", or simple "find/find in files" function of your text editor. Many editors will automatically highlight each occurrence of a currently selected/searched for variable.
• If you can, use the debugger to simply see how everything works. Learn the keyboard shortcuts for "step into/step out/step over".
• If the code you are trying to understand is particularly large (for example, an entire library), rather than a single function, then you should start with the documentation. Read the README. Look at the files. Try to guess what is in each file. Then go read some documentation. Then go back to files. Start reading the largest one, make a list of structures/classes/functions that are used the most often. Find them all, read them, understand them, read their documentation. Then you should be able understand any part of the library you need to.

Written 7 Jul, 2014. 592 views.

Suggest Edits

Upvote15

Downvote

Comment

Share

R. Drew Davis

2 upvotes by John Su and Alexander Lukyanov.

If you are trying to understand a large body of source code, and documentation to guide you is scarce, I find that it helps to sketch out diagrams of how all the pieces relate to each other.  Likely a good way to get started is to get yourself a copy of the code and work out how to build the application executable from source.  Tools that help you probe for a given function or variable (e.g. cscope for C/and its relatives) can be super helpful.    Worst case scenario, grep is your friend.  I haven't tried it, but I see there's a pyscope that says it can build a cscope index for accessing a body of Python code.

Do the world a favor and generate a tour guide document to help people who find themselves wanting to understand the same body of source in the future.   Fine details will change, but the overall structure of the application likely will be stable for long stretches of time.

sloccount is another way to summarize code by size and complexity.   May help you zero in on the most gnarly pieces of the application (or depending on your point of view, may tell you when to avert your eyes).

I'm old fashioned enough that when I'm digging in detail into a specific complicated module, I like to have a pretty-printed hard copy of the source code.    I remember one TCL program I was wrestling with.    The in-house TCL pretty-printer program choked on some of the code.    Turned out there were some coding irregularities in the modules that made the pretty printer choke, so on the one hand I worked with the maintainer of the pretty-printer program to make it more robust in the face of errors in TCL source files, but on the other hand, I cleaned up those flagged modules and looked into the test data to understand why those errors hadn't already been known and corrected.   Once you have a hard copy, then a 3-ring binder, paper notebook dividers, a highlighter, a pen and a stash of sticky-notes to bookmark important pages can all help in your expedition.

If your target is still undergoing rapid change, then my suggestion of getting a hardcopy may be unwise as the hardcopy print out won't automatically reflect the latest in changes that are going on even as you are trying to get your footing.

Happy digging.