When you don’t spring clean your comments

Refactor: restructure the source code of a program to improve its operation without changing the functionality.

Happy Spring Day! According to the calendar, today is Spring Day in South Africa, but the weather seems to disagree.

I wanted to write something about programming and Spring – and I don’t mean the Spring framework. I couldn’t think of anything. (If you can, please share it with me.)

But the idea of Spring led to the idea of spring cleaning, and that led to the idea of spring cleaning (aka refactoring) code. And from there it was only a short jump to comments in code.

Comments for the non-programmer

For those of you who are not programmers, a comment is exactly what the name says. It’s some extra information that the programmer writes in his/her/their code. 

Comments are intended for the programmer only. So they are marked in a special way to ensure that the compiler ignores them when it executes the code. This means that users will never see the comments.

Do you use lots of Excel formulas? Then you know what it’s like to look at a spreadsheet that you created months ago, and not be able to remember why you used the formulas the way you did. It helps if you put a note in the cell to remind yourself. That’s the concept of a comment.

The purpose of comments is to help the next programmer understand why the code was written that way. Programmers also often use comments to “switch off” parts of the code while they are looking for a bug.

When you want to bash your computer

Programming can be very rewarding, and also intensely frustrating. And when programmers get frustrated, they sometimes express that in their comments.

I looked for some examples of funny comments that people have left behind in their code.

This comment is (almost) famous:

//When I wrote this, only God and I understood what I was doing
//Now, God only knows

Here’s another favourite:

// I dedicate all this code, all my work, to my wife, Darlene, who will 
// have to support me and our three children and the dog once it gets 
// released into the public.

Unfortunately, these comments are often true:

// I am not sure if we need this, but too scared to delete.



// I am not sure why this works but it fixes the problem.

// This is black magic
// from some stackoverflow link
// Don't play with magic, it can BITE.

Here are a few more explicit warnings to the next poor programmer

/*
* Dear maintainer:
*
* Once you are done trying to 'optimize' this routine,
* and have realized what a terrible mistake that was,
* please increment the following counter as a warning
* to the next guy:
*
* total_hours_wasted_here = 42
 */



/*
* You may think you know what the following code does.
* But you dont. Trust me.
* Fiddle with it, and youll spend many a sleepless
* night cursing the moment you thought youd be clever
* enough to "optimize" the code below.
* Now close this file and go play with something else.
 */

This one is pure art:

// Replaces with spaces the braces in cases where braces in places cause stasis 
   $str = str_replace(array("\{","\}")," ",$str);

You can find some more on https://www.techiedelight.com/best-comments-source-code-ever/

To comment or not to comment

Comments in code can be contentious. I use comments liberally when teaching, because they help people understand the concepts as they learn.

Some programmers believe that your code should be so clear that it does not need comments. A valid view, if a little optimistic. But it is true that comments do not make up for bad code.

It’s really about the context and how you use them. Well-written, meaningful comments are helpful. Unnecessary comments add clutter. Out-of-date comments create confusion.

One rule of thumb: comments answer the question “Why?” and the code answers the question “How?”.

The moral of the story: when you refactor your code, remember to spring clean your comments too.

Have you come across some strange comments left by the previous programmer? I’d love to hear about them.