How to Read Source Code

  • Article

Part I - General Steps and Principles

1. Define a Clear Goal
- what's the purpose? to know how, to own components, to modify and extend?
- results driven, what's the final outcome?

2. Know it as Client User
- read user manual
- get an overall big picture
- know what it can do and what can't
- what is it suitable for and what not

3. Thinking Before Reading
- what if you design the whole system?
- what's the core challenge?
- write down your questions and concerns
- read with questions

4. Know the Architecture/Components
- know the overall architecture first
- devide the whole system into components
- identify what to focus, what to ignore
- use build file to identify component dependencies
- try building it

5. Read Specific Detail
- make a SMART plan
- focus on core logics
- ignore trivial parts
- start from entry point: main/wmain funtion
- identify thread creation/termination
- identify the main loop (server application)
- identify core data structure
- identify operations on core DS
- noting/documenting/charting down while reading

6. Producing Results
- big picture from user's perspective
- big picture from dev's perspective
- arch/logic for individual component
- summerize core data structure
- practice: build/deploy/use/debug/modify/hack the system
- comments on the implementation(what's good, what's bad, what learned)

7. Misc Tips
- read doc(user manual, design doc) before code
- get core data structure doc first if possible
- read the code in both static and dynamic(debug) way
- debug/step into a particular execution scenario
- read code iteratively, don't deep into detail in the beginning
- use interface/contract to separate concerns
- overall -> detail, but just detail on small areas
- leverage code comprehension tools to get static information
- print out core code and read them on real papers
- you can write unit test / use case for the software
- consider refactoring the code(kind of active reading) if unit tests are given
- if it's really hard to read, rewrite it!

Part II - Tools

One
of the most frequent activities when reading code is navigating among
those source codes. So tools that help navigating are important to
improve the reading efficiency. Here are some popular tools for this
purpose:

1. Source Code Index Generator
cscope https://cscope.sourceforge.net/
ctags https://ctags.sourceforge.net/

2. GUI Frontend for Index Generator
kscope https://kscope.sourceforge.net/
cbrowser https://cbrowser.sourceforge.net

3. Code Index Generating and Navigating
Source Navigator https://sourcenav.sourceforge.net/
Source Insight https://www.sourceinsight.com/
LXR https://lxr.linux.no/

4. For C Language ONLY
CXRef https://www.gedanken.demon.co.uk/cxref/
cflow https://www.gnu.org/software/cflow/

[Reference]
1. Code Comprehension Tool https://www.cs.ubc.ca/~murphy/cs319/index.html
2. Code Doc Generating Tool https://www.stack.nl/~dimitri/doxygen/links.html
3. Survey on Code Comp. Tools https://www.grok2.com/code_comprehension.html
4. Tips for Code Reading https://c2.com/cgi/wiki?TipsForReadingCode
5. Read VS Rewrite https://www.joelonsoftware.com/articles/fog0000000069.html