No Comments Please
The history of electricity is fascinating. From when people first encountered “static electricity” by rubbing two materials together to Benjamin Franklin’s kite getting struck by lightning and finally to the invention of the light bulb. What was the key factor in allowing all this discovery and innovation to occur? Communication. You might have heard this famous quote from Issac Newton, “If I have seen further, it is by standing on the shoulders of giants”. Whether it be through word of mouth or writing, ideas must be transferred unless we want to start from square one over and over again. Imagine if Thomas Edison had no prior works to base his light bulb off of: we might not be where we are today!
In programming applications, it is important that we utilize this idea of “standing on the shoulder of giants”. To allow for this to happen, it is important that we communicate our ideas clearly so our work can be understood in the future. In code, this can be done by adding documentation, or comments in the file itself. Before we discuss comments though, let’s first consider what it’s like to translate something.
Translation: Not Found
Have you ever had to read someone else’s handwriting and couldn’t figure out what it is they wrote? If you haven’t, I hope you continue to have good luck. For those that have experienced this, it’s even worse when you are in a notes-heavy class. The professor is writing a mile a minute and you can barely translate what she/he wrote, let alone keep up!
Now, imagine I gave you a note with the text “op aolyl” on it . What does the message say? Go ahead, I’ll give you a few seconds.
What do you mean you don’t know what the note says? Oh. I forgot to tell you that I am shifting each letter in the original message by 7 to get the message “op aolyl”. So ‘h’ translates to ‘o’, ‘i’ to ‘p’, and so on. If you shift each letter in “op aolyl” back 7 spots in the alphabet, you will get the original message: “hi there”. If you were curious, this kind of “translation” is called a Caesar Cipher.
Of course I believe you could have figured this out had I told the extra bit of information: “I used the Caesar Cipher with a shift of 7 on this message”. Knowing this information makes it easy to decipher what is going on. To relate this to coding, imagine you were to look at someone else’s code or even looking at your own code in the future. What if there were no comments to tell you what was happening? The code might as well look like the “op aolyl” message from earlier without the necessary information to decipher it. Given enough time, you could probably figure out what was going on, but it would have been nice if you had the comments there to tell you in the first place.
Standing on the Shoulders of Giants
Alright, so communication is important in the transferring of ideas. How would that look in code?
This is a tiny code snippet from Spotify Voice that adds tracks to a list. Without the comment, it might have taken 30 seconds to figure this out, but with the comment, you know instantly what it does. This is a simple example, but you can imagine that when the code becomes longer and more complex than this, it would be nice to have comments explaining the logic.
When you comment code, not only are you doing yourself a favor, but also other people who have to interact with your code. It can be hard to stop every once in a while and document what you did, but it saves a lot of time in the future that could be better spent looking at dog gifs like this one.
At the end of the day, commenting code is tedious and takes effort, but it pays off immensely in the future when you come back to a project and wonder what the hell the code you’re looking at does.
