The Three Functions of Comments in Programming

If you don't program computers, you probably won't find this post interesting, so just enjoy the raccoon picture, and I'll see you next week.

In computer programming, a "comment" is a series of characters that is meant for the programmer, and not the computer, to read.

When you program, you often do it in an "editor," and most editors help you out by color-coding the comments (among other things) so that you can readily see what's a comment and what's actual code.

However, there are three distinct functions of comments, and I think they deserve different colors.

  1. Comments as explanation and documentation. Some comments are there to explain the code someone trying to read the code. Computer programs are full of jargon, and comments like this help the programmer understand what the code is doing. This is what most people think comments are for.
  2. "Commenting out" code so that it doesn't run.  This is often done during debugging, when, for example, a bit of code isn't working, or taking too long while you find some error elsewhere, or when you no longer want that functionality but might in the future (if you never wanted that functionality again you'd just delete the code). 
  3. Commenting out code that is there for debugging. Sometimes I will put in a print statement, usually, so that when I run the program I can tell what it's doing. When the program is working, I don't need that output, so I can get rid of these lines. However, since I might have to go back and debug again, I like to leave in the debugging code for later use. So I comment it out. 

They're different enough functions that I think they deserve their own color coding-- particularly 1 and 2. 3 can get grouped in with 2 in a pinch.

But I think code would be easier to read if the explanation, for example, were distinctly colored.

In the meantime I have my own workarounds. I program in python. To comment in python you put a # mark, and everything after that on the line is a comment.

For explanation comments (type 1), I use a double hash: ##
For non-working code comments (type 2), I use a single hash:  # (this is because it should be short and easy to remove and retype)
For the commenting of debugging code, I use "# FDO " which stands for "For Debugging Only."

Works for me. There should be three ways to comment, and each should get their own color. But until then, that's my little hack to make them different.

Bookmark and Share


Cindy said…
I hadn't really thought about commenting before. I knew its intended purpose but I didn't realize that other people used it for debugging or in case they might need a function again. I guess this comes from working in a psychology department rather than a cognitive science department (which would be bliss). I'm the only person in the department who can program.
I like your idea about different colors for the different code functions. However, it would be very difficult for the program editor to be able to do that because it would require parsing and understanding the comment in order to be able to assign the correct color.
Or maybe you just wanted a way to pick between three different commenting options? That would be a lot easier.
Can you tell I live in a fantasy world where I see software being created that actually helps us to think and work?
Jim Davies said…
The idea is that the comments can be made in different ways

# like this
## or like this
/* or like this */

and the different kinds of notation can have different colors.

Popular Posts