In the great repositories of programming errors I found this little jewel. Aren’t we glad we had all those comments to guide us?

This is another way that comments become lies over time: nobody maintains them. Nobody maintains them because they litter up the code and programmers have to learn to look past them to see what code is doing. Sometimes we have to page down through a lot of them to find a useful bit of code. It’s why we’re glad for syntax highlighting, so we can more easily ignore them all.

The answer is probably not to write more comments, or to write them in a catchy style, or to demand that programmers look at them more carefully. Probably the answer is to obviate them (write them into the code) and delete them. We are all trained to look rather carefully at the code.

Looking at this example, can you tell why the parental control is set to three? Probably not. You could guess. More likely, you would agree if it were set to DEFAULT_SAFETY_LEVEL, but if DEFAULT_SAFETY_LEVEL is 3 you are no better off.

But what if there were constants like NO_FILTERING, MODERATE_FILTERING, and STRICT_FILTERING and DEFAULT_FILTERING_LEVEL were set to STRICT_FILTERING, and the variable were ‘parental_filtering_level’? Then there is a lot more information available to you. So you’d delete the comments. When you were testing DEFAULT_FILTERING_LEVEL would be NO_FILTERING, later you would change it to MODERATE_FILTERING , and maybe pre-release you would set it to STRICT_FILTERING. The change and its check-in comments would tell the whole story.

That having been said, I don’t know that I have interpreted the variable and setting correctly. Even having comments doesn’t tell me what the variable and the value ‘1’,’2’, or ‘3’ really mean.

This is what I mean when I say that I don’t like comments. They need to be obviated first, and then deleted. Sometimes it is even best to delete them all, and then try to figure out the code as a means of training oneself to write more descriptive code.

If the code cannot express itself, then a comment might be acceptable. If the code does not express itself, the code should be fixed. Either way, obsolete comments and those that do not add value should be dropped like a hot rock.