If you work as a developer, you probably spend a large amount of time in your editor. You are adding features, improving tests, looking for bugs, reviewing changes, and otherwise looking at the code.
When I started programming, screens were a lot smaller and almost no one had space on their desk for more than one monitor. If you wanted to get a good view of a large amount of code, you printed it out and went over it with a pencil and highlighter. Quite often, this allowed you to notice issues that you didn’t see in your editor.
The important point is not printing the code, it’s viewing your code in a different way. Writers and proofreaders have known forever that it is sometimes useful to read a passage aloud to spot mistakes. The point is changing how you experience the work.
When you are looking at something over and over the same way, you stop seeing what is there and begin to see what you expect. You develop blind spots around the details of what you are seeing. This is why a different person sometimes spots something obvious that you’ve overlooked.
Different Views of the Code
How are some different ways you can interact with your code:
- Look at a diff from a previous version
- Explain your changes to someone else
- Change the font
- Change syntax highlighting
- Look at it in a different tool
- Print out a file and read it away from the computer
- Display the list of functions/methods
- Generate a list of class or module names
Diffs
If you are using a version control system like git, this is pretty easy. If you are not (you should be), using a standalone diff tool is still worthwhile. The main benefit you get from comparing the current version to the old one is seeing what may have changed that you didn’t intend or forgot.
Did you remove a messy piece of error handling, with the intent of rewriting it once the change was made but forgot it? Did you add an if test without considering the else condition? Did you rename a class, without considering related classes?
Explaining the Code to Someone
This is similar to the writer trick of reading out loud. You are changing the mode that you are interacting with the code, probably in multiple ways.
First of all, you will not read the code token by token. You look at the code and translate it into English (or your native language). This forces you to think about what you are seeing instead of just scanning the code.
Second, you are speaking your understanding out loud, which uses different parts of your brain than reading silently. You are also hearing what you are saying, which gives another mode for interacting with the code.
Third, the person you are explaining to may ask questions for clarification, which makes you less likely to gloss over weak parts of the explanation.
Amusingly the first two effects are so effective that you do not really need to explain to someone who understands the code. I have seen similar advantages with explaining to a spouse (my wife has a technical background, but is not a programmer), a pet, and even a rubber duck.
Different Font
Part of the idea here is to make the code look different. Pick a wider, monospace font to make thin punctuation characters stand out. Pick a less comfortable font to force you to read rather than just skim. Use a tiny font to highlight the structure of the code, instead of just the syntax.
Syntax Highlighting
If you don’t use syntax highlighting normally, turn it on. If you do use it, change the color scheme.
The idea of syntax highlighting is to remind you of how the parser will see your code. The parser is dumb, it does not know what you mean only what you wrote. Sometimes when you make a mistake, it’s because what you meant is not what you wrote.
Changing your syntax highlighting may make you look at the code in a different way.
Different Tool
If you store your code on github, gitlab, or some other version control site, try viewing your code there. Often the other tool will have different display characteristics: font, syntax coloring, page width, etc. This will make you code look slightly different and make reading it a little different from looking at the same editor screen.
Printed Version
It’s kind of old school, but printing a section of code can still be helpful. Unless you have carefully tuned your environment, the text on the page will look a little different than it does on the screen. The sizing may be different. The margins will have a visual effect that they don’t on the screen.
More importantly, you can change your physical environment: move to another location, have different lighting, highlight interesting bits, write notes, etc. You may be able to lay multiple pages out on a surface and see more than you could on one monitor. This makes larger patterns easier to see.
Method/Function List
This approach is more useful for design than troubleshooting. Obscuring all of the code except the method names (for a class) or functions (for a module) is useful for exploring whether you have a single responsibility or many.
It can also help point out if the mental model embodied in the code has shifted over time. For example, do any new methods follow the same terminology as the others.
Class/Module List
This is a larger version of the previous concept. Are the names of the similar modules or classes at similar levels of abstraction? Are they related to the same metaphors? Has the code mixed metaphors in a confusing way?
Conclusion
Many programming errors happen because what you think you wrote is not what you actually wrote. The compiler/interpreter is not smart enough to know what you meant.
When the code doesn’t do what you think it should, sometimes a change in perspective is all you need.