Notes on Reading Code

Motivating and Relevant Articles 

Useful tools for code reading

Tools for annotating code


Useful techniques discovered during the course

Use Cases for reading code


Reading Patterns
A proposed pattern on reading code (would be cool to have a rough pattern for each of the use cases) :

This is a rough sketch of a guideline based on what we learned during the reading-code P2PU course.

1. Read the README

No project worth its salt these days comes without a README file, this is your first contact with it. Make sure you understand what the project is about, (yes sounds silly but there are some tricky definitions out there) what's the particular problem it solves, and how it differs from previous attempts on the same area.

2. Fork/clone/checkout the code.

While this might seem obvious at first, for many projects there's a whole process involved, and therefore many provide some documentation on the the guidelines for getting the code, building and submitting patches, reviewing other's patches, etc.
Don't delve too deep into this yet, just enough to get a working copy of the project on your enviroment.

3. Build a "Hello World" test.

There's usually a very basic use case you can implement in order to test if your source is functional, this may vary greatly depending on the kind of project you are working on (tools, libraries, frameworks, applications, games, etc..), but getting the first run is crucial to the next step.

4. Identify the core functionality or "bootstrap" code.

This basically boils down to find where in the source code is defined the method, function or module that allows this program to run in the first place. For example, for web frameworks it's interesting to see where the HTTP server is defined and how it bootstraps itself. 

The very basic Jquery example would be an html file with the following script:

<code>
<script>
 $(document).ready(function() {
   $("a").click(function() {
     alert("Hello world!");
   });
 });
 </script>
 </code>

If we were to find how Jquery works based on this example, we could begin by looking at where the $ variable and the "ready" function are declared. This is where grep comes in handy as explained later on.

5. Most big open source projects have online and public bug and task trackers. This is a really useful way to find specific things to track down. 

6. Try documenting the code yourself. What style of architecture is it, what are the major pieces of the app, and how do they talk to each other? 

7. Try reading it with someone else, or describing it out loud. 


Checklist for Open Source Developers
[ ] one README for each component, stating its purpose
[ ] overview of internal architecture
[ ] inline comments and API documentation for each class/method
[ ] build instructions
[ ] example code showcasing typical usage


Nice to have
[ ] online code browser
[ ] online documentation
[ ] interactive shell providing a sandbox to experiment with the project


Possible Future Reading Code course themes

Further Readings