When developing a new program—especially when trying out many different things—it’s common to pepper your code with various messages that are displayed when the program reaches a particular point or when it encounters a condition that you thought was impossible. I suspect every programmer has run into a message or assertion that says, “this can’t happen.” The joke is that it did happen.
It’s also common to be pretty liberal with terse comments that are little more than notes to oneself about the current technique being tried.
Both are understandable. Every programmer I’ve known has done similar things. However, it’s also quite common to leave those comments and messages in the code after the problem is solved and you’ve moved on to other things. Particularly in a fast-paced environment, you often have little time to go through and “clean up” your code once you have it working. And therein lies the problem.
All too often those comments and debug error messages are…well, let’s just say “colorful.” In addition, programmers are known to editorialize in their comments—often to the point of ranting.
You may think that when you’re working by yourself or in a small team, such things shouldn’t matter. After all, you know that your fellow team members won’t be offended by your use of colorful language. Thinking that way is a mistake because eventually somebody else is going to see your code. Perhaps you’ll bring on a new team member who is offended. Or maybe you’ll want to present the code as a sample in an interview for your next job.
Either of those two would be embarrassing. But suppose one of your colorful messages pops up on the screen when your boss is demonstrating the program to a potential client. That could be disastrous. I’ve seen it happen. Fortunately it wasn’t one of my colorful error messages.
You’re mistaken if you think that source code comments pose less of a problem. I was involved with a company that was acquired by another, and part of the “due diligence” involved having the acquiring company’s lead programmers look over the source code. They were mostly looking for stuff that shouldn’t be there (stolen code, for example), and verifying that everyting that should be there, was. Early on, one reviewer stumbled upon a long and profane ranting comment in the source code and as a result was highly critical of all the code he reviewed. Fair or not, that one comment colored his perception of the entire project.
Even if you’re working by yourself, the likelihood of your code being seen by others is very high. The likelihood of somebody else seeing the output from your programs is even higher. People will judge you by the contents of your comments and error messages, just as they will judge you by the quality of your code and how well your programs work.
Unless you’re absolutely certain that your program will not be seen by anybody else, you should treat it like any other type of formal communication. [Hint: you can’t make that guarantee.] You wouldn’t include profanity or ranting editorialization in a design document you’re presenting to a client, so such things shouldn’t be in your source code.
Just west of Taylor on U.S. 79, I noticed a sign that said, “Frame Switch.” I caught that sign coming back, too, and was curious because it looks just like the signs that announce the little towns along the route. Except this sign doesn’t show the population.