Notes on Reading Code
Motivating and Relevant Articles
Useful tools for code reading
- grep with -r (recursive), -i (case-insensitive), --color (highlight match) and -n (line number) options
- text editor with syntax highlighting
- The Deconstructed Series (Javascript-specific): http://www.keyframesandcode.com/resources/javascript/deconstructed/
- Firebug or Chrome developer tools
- git log --name-status, to follow the history of the project with list of files modified
- git log -p filename, to follow the evolution of a single file, seeing differences at each step
Tools for annotating code
Useful techniques discovered during the course
- breaking the code: stack traces provide a lot of information
- Have a target platform to build and run the code on
- Bug and Issue Trackers
Use Cases for reading code
- Learning a language
- Using an undocumented library
- Tracking down a bug or unexpected behaviour
- For fun :)
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
- Famous pieces of code
- the code of a programming language
- machine learning and other more sophisticated algorithm implementations (eg. comparing solutions on projecteuler.net)
- more small and/or un-documented code snippets
- security audits
- outlining where and how to add new features (without actually implementing them)
Further Readings
- Peter Seibel's Coders at Work [http://www.codersatwork.com/] features interviews of famous programmers with relevant experience in various domains. Some of the questions asked are particularly relevant in the scope of this course:
- "How do you tackle reading source code? Even reading something in a programming language you already know us a tricky problem."
- "How do you read a big program that you didn't write?"
- "Do you still read code for fun, as opposed to reading it because you need to work with it?"
- "Do you find code beautiful? Is there an aesthetic beyond maintainability?"
- "What are the characteristics that make code easier to read?"
- "Can you talk a bit about how you conduct a code reading?"
- "Do you ever step through code as a way of understanding it?"