How to Read Source Code

文章来源
https://blogs.msdn.microsoft.com/csliu/2009/03/04/how-to-read-source-code/
作者
https://social.msdn.microsoft.com/profile/changl

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 http://cscope.sourceforge.net/
   ctags http://ctags.sourceforge.net/

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

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

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

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