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.