1 to 3 minute read

We've all been there. Whether on a personal project or at work, we at one time knew exactly how our code worked from line to line.

And yet, literally the next day, we find ourselves lost in our own code. We try to read the small comments we've written and re-read the code a trillion times, but it just never seems to re-enter our brains.

This is important to fix for 3 simple reasons:

1. It wastes LOTS of valuable time that could've went into something else

If you already have a job in programming, you know how stressful deadlines can be. So saving every hour you can save is crucial in making sure you never get past that deadline.
This is essential to make your job much more stress-free, especially if you get that unfortunate moment before a deadline!
If you're not yet employed, learning how to deal with this now is the best way to ensure that you can have a smooth transition from college [or high school] to
the job market.

2. It's discouraging and thus makes you procrastinate more

A similar feeling to your boss giving you extra work out of nowhere.

 
3. It's just incredibly unpleasent

Who likes to re-read their code over and over again? We want to move on. We want to get to the "next step" of our program's development. It's a huge time sink.

But first, we must understand why

Why do we forget everything the next day?

When we're in a deep state of work, we are so focused on our work that we can remember the purpose of almost every single line of code that we've written (or at least quickly recall their purpose). Think of it like RAM: It's great, but when you reboot your computer it's all gone.

Effectively, you are storing all of your knowledge of how your code works in your brain's RAM, and expecting yourself to remember that information the next day.

Your brain has essentially been reboot. How do you expect yourself to remember any of that information?

Maybe you already know this, so you tried adding comments to your code. But as you've probably already found out, that doesn't always work. Why?

 

Why comments alone don't work all of the time

Comments are great. No one's denying that.

However, a program must be understood down to its detail. A single forgotten semicolon somewhere around your code can break it entirely.

Unless if you make half your program comments and the other half code, it's not going to guarantee that you'll quickly understand your code once you open the coding editor. In fact, it might even add confusion, since your code will be crowded with comments and actual code.

Take a look at this simple hypothetical example:

Altough the code is a simple 18 line fizzbuzz "simulator" python program, explaining it thoroughly relatively took a lot of space.

Of course, when it comes to such a simple program, it shouldn't be a problem. Comments are probably not even necessary.

However, imagine how crowded detailed comments can become when programming a complex machine learning program or coding a whole website's backend? It'd make your code unnecessarily very hard to read.

However, there is a simpler solution that not only makes both your comments and code more readable, but also is completely free... And you can start today.

 

A different way to structure your comments

As we mentionned earlier, comments are great!

This is why you should use them in your code. But you have to use them strategically.

A better strategy to explain your code to your future self in detail is by creating a text file, call it "(your program's name)-EXPLAINED.txt", and writing about how your code works in pure detail.

Then, write comments as you would usually do to broadly explain how each function and operation works, but point to the section of your text file's essay that specifically talks about it in pure detail. That way if your future self doesn't find the broad definition sufficient, he can read about it on the text file.

This can include why you picked that algorithm over some other algorithm, how you came up with it, why you think it's efficient, how you think it can be improved, how each part of the function works and why/how they're interrelated, what you think could be improved, and so on.

You don't have to make it more complicated than it actually is, but generally more information is better.

It should look a bit like this:

Altough this kind of program doesn't need much commenting as it'd be unnecessary, it'd certainly make your much more complex programs much easier and faster to read and avoid those very frustrating "Now only God knows how this code works" moments.

And after writing your essay, you can go to sleep with peace of mind that the next day you won't be confused as to how your code works again.

If you struggle with this again in the future though, may this mug serve you as therapy.