Item 34: Compile Comments Into Code to Get Unstuck

TODO: Rearrange so this is the last one!

Have you ever felt overwhelmed when trying to implement a piece of code where you just can’t get your thoughts straight? Maybe it’s a part of the codebase you’ve never worked on. Maybe it’s a brand new approach to a problem that you’re used to solving a different way. Maybe you’re working with an unfamiliar framework or programming language. In any case, if you feel like you know what you wanna do, but can’t seem to put it into syntax, try this:

Write out the routine line by line as inline comments. Once you’ve done that, go back to each line of comment, and rewrite it as code.

I have found this to be a simple, yet effective way of getting my ideas out of my head and into code. It’s effective because it allows you to make one less conceptual hop — you only have to write the idea in English, and not in code. Many times, it’s hard to write the code because you’re not sure how to express the idea in English. Once you know how to express the idea in English, you can then worry about translating it into your programming language.

After all, any software is only as good as it’s representation of the underlying idea. By focusing on articulating the underlying idea in natural language, you will inevitably express it better in code. Once you have done so, you will step back and see that even if the code isn’t perfect, you have laid a solid foundation for the overall product, one that you can not only build upon, but maintain and scale as other engineers come into the codebase.

More in that now, in part III.