Source Code Reading Check-List Part 1

Code Reading check-list giving tips-n-tricks:

1. Search the source code repository for expert coders i.e. by author name. Reading high-quality code helps to develop good coding habits.
2. Power browsing. Keep track of the goals before you start browsing code. Note them down and keep referring to them. This will help ensure you stick to the goals you started out with.
3. All systems are simple. The most complex software is written quite simply. It needs to be dumbed down to the level of a computer. Get over your awe of a complex system. There is no magic involved.
4. Backtrack from the first appearance of a bug to its actual origin.
5. Get Debugging information using the following methods:
• Debugger
• Compiler warning/intermediate code
• strace - trace of calls to operating system functions like open(), read() etc.
• Logs created by the database, library, or application.
• Network monitoring tools - wireshark,
• Windows message capture
6. To add features or extend existing source code, try to find the closest matching existing code. Simply copy-paste code and settings followed by customizing it will suffice. Note: The greater the similarity of features between your code and existing code the less work you have to put in the customization.
7. Create a KeyWord-List by examining the source for the following patterns:
• String messages,
  
• Log statements,
  
• Menu Items,
  
• Function names,
• Macros,
  
• Other search terms - (You'll need to adapt the search terms as per coding style)
  
• Example: getXYZ(), setXYZ(), updateXYZ(), selectXYZ(), addXYZ(), updateXYZ(), deleteXYZ() etc which point to behaviour control mechanisms.
  
8. Keep adding to the KeyWord-List as you get more familiar with the source code conventions and style. This list will be most useful for future reference by you or a team member.
   
9. Pay close attention to compiler warnings and error messages. You can reduce days of work by easily finding to areas of mismatch (without even having to read code) Esp. useful while porting and modifying existing source.
10. Add unit-tests for regression checking the source code. This allows you to refactor code confidently without worrying about causing more bugs than you fix. Any tests that fail will point immediately to the source and scope of the bug.
11. Esp. when working with obfuscated code, sometimes writing your own code is easier than trying to understand, refactor and reuse someone else's code.
12. There are a few basic approaches to source reading:
• Bottom-up vs Top-Down i.e. implementation layer vs. managing layer,
  
• Easy modules vs. Complex modules or Easy code vs Complex code,
  
• Unit Tests vs Source code - Usage versus Implementation
  
• Given a choice try to take the easy way out for the time being.
  
• You can always come back later to difficult parts with more insight from your earlier efforts.
13. Search for nuggets of information in the following places:
• file and directory organization - (names of files/folders are suggestive of usage),
• makefiles/project files - (project dependencies often a source of versioning bugs)
  
• settings mechanism - files, cmd-line options, environment variables, hard-coded values, keywords used in source code.
  
• UI mechanism - (understand the functionality by executing test code)
  
• Documentation - specs, design, readmes, forums, bug reports, user guide, marketing docs, presentations.

See Also:
Code Reading : The Open Source Perspective by Diomidis Spinellis