Old School Code Review – Pen & Paper

Every once in a while when I get to a certain point in a project, I like to back up and make sure I’m not missing the forest for the trees.  That’s when I print out a lot of code and head for the coffee shop.

Getting down and dirty in the code and living in the code editor is what programmers really enjoy doing, but it’s good sometimes to take a few steps back.  I start by identifying all of the major pieces of code (if a class has only has a few lines and one function, I can probably skip it for this review) and make sure I’ve got a stack of paper in the printer.  Next, I make sure that whatever IDE or editor I’m using supports syntax highlighting when printing because not all of them do.  When I’m programming with Unity, this typically means UniSCITE which has syntax highlighting in both code and print and supports highlighting the various keywords and comments and things like that.  Of critical importance is that comments and comment blocks are colored, preferably in a color like green that is still readable but doesn’t just jump off the page.  You want your code to jump off the page at you, not your comments.  If your editor prints out page numbers and filenames on each page at the top or bottom — all the better.

Next, I print it all out and head to the coffee shop.  After I settle in with a large cup of black coffee, I start by going through every page of every file looking over the code.  Sometimes I’ll find things that are redundant, or things that will speed up a section by moving variables or initializations outside of a loop or things that can be combined.  I use my pen and write notes on the page as I go, whether it’s a comment to myself about something that could be optimized or moved to another class, something I want to look into for optimization, or something I want to check out because I think it might be the source of trouble I’m having.  It’s all too easy to dig around in the code and be lazy (and sloppy) when you’re trying to optimize or troubleshoot, but if you can get an overview, you’ll often see a LOT of things that you missed before.

As I’m going through the code, I usually end up using an extra piece of paper or two to write out more notes on about different ways to approach a particular piece of code, or a new module/class that I want to write to combine some existing functionality.  After I’ve gone through all of the code looking for the line-by-line, function-by-function type stuff, I’m also going to be a lot more familiar with all parts of the code.  The last time I did this in my game, there were parts of the code that I wrote months earlier and hadn’t touched since because they were working fine.  However, having gone through and re-familiarized myself with everything, I realized that there was a lot of room for improvement and consolidation.  I ended up finding and fixing a few bugs, getting a better idea of how (and where) to redo a few things and consolidating some code by combining functions and making them a little more flexible.

If your code would take up a ream of paper (or even half a ream), then this technique probably isn’t for you.  Most of the projects that I’m doing, even with a couple thousand lines of code, don’t end up being a huge stack of paper.  Even if it did end up being quite a bit, you could still do this same thing with just one or two of the larger classes/files.  I’ve also had success using this technique if I’m trying to get familiar with someone else’s code, whether it’s an existing project I’m picking up to work on or an open source project that I’m trying to get more familiar with.  I’ve used this technique many, many times over the years and it’s always proved useful to some degree every single time I’ve used it.  Typically, it yields very good results and I come away with better code, cleaner code and faster code.  When you’re trying to distinguish yourself from all the other pieces of software out there, these things can make a huge difference.  Lastly, if you give this a shot or have similar practices, I’d love to hear about the results.

This blog post is part of the #iDevBlogADay initiative for indie iOS developers.  Click here to read more posts from the iDevBlogADay website.