Print out your code. On paper.

Cover photo CC-BY-SA 4.0, by Corvair

Reading code is hard work—in some ways harder than writing it—so most of us have a tendency to avoid looking closely. There is a practice I learned about long ago called desk checking that seems to have gone out of favor in a world of incredibly sophisticated IDEs, but I believe it still has a lot of value.

To desk check your code:

1. Print it out
2. Find a quiet room
3. Bring a pencil
4. Leave all devices behind. Take off your smart watch. Fold up your laptop. Leave your phone at your desk. This is between you and the code.
5. Sit there and read your code line by line. Mark it up as you go.

You’ll learn something every time you do this.

Here are some questions you can ask:

• Are the labels right? There is so much more nuance in English than, say, in Python, so it follows that a lot of defects in code stem from English misunderstandings between programmers, rather than Python misunderstandings. On the other side of the coin, the code is an opportunity to align our mental models and problem domain vocabulary with our teammates. This can get very philosophical.
• Are the abstractions right? What do we know about the problem domain now that wasn’t as clear when this code was written? Given what we know now, how can we bring this code closer to our current understanding?
• What simple refactorings would bring more clarity and elegance to the code? What is no longer needed, that we anticipated needing before? What can be decomposed further?

You’ll also find bugs, naturally. When you slow down and look, bugs will just start crawling right off the page. Sometimes they will take your breath away, and you’ll leave wondering how the damn thing ever ran in the first place.
How to print out code, with syntax highlighting:

There’s an ancient but useful command line utility for this, called enscript.

On MacOS, you’ll need to brew install enscript first.

On Linux, you may already have it. If not, look for the package enscript or download it here.

To print your code, run:

enscript -1rG --line-numbers -p out.ps --highlight=python \
  -c inputfile.py

The output file will look something like this:

Then you can either open out.ps (on MacOS to open in your default PostScript viewer), or print it to your default printer with lpr out.ps.

Enscript has a lot of options. Here are the most valuable options:

-1 -2 -3 -4 number of columns per page
-r rotate (landscape mode)
-G fancy header (with filename, date & time)
--color=1 if you have a color printer
-w html if you want HTML output instead of PostScript
--help-highlight will show which languages have syntax highlighting available

Here’s a nice looking version that adds --color=1 and -2. If your line lengths aren’t out of control, this is a good starting point.

enscript -2rG --line-numbers -p out.ps --highlight=python \
  --color=1 -c inputfile.py

Code can be quite beautiful at rest—if you take the time to really appreciate it.

You have the tools, now set aside the time.

Sources:
Printing code on MacOS
Linux Printing Guide