Commenting Code

There’s an interesting thread on SlashDot about when and how to comment code.

Lots of programmers seem to think that comments are a waste of time, but when I interview a programmer I always ask about how and when the programmer comments. I’ve been known to ask a programmer to walk through commented code, explaining what it does. If you really know what you’re doing, and your code, you should be able to explain it to someone who knows the basic concepts of programming and understands the task at hand.

I think comments are important, not only for future maintainers, but as a help to the coder who writes them. You will forget what you meant a particularly brilliant bit of code to do when you come back to it six months later, or even the next morning after an all nighter. Comments will help you remember. Make them descriptive, and specific, and you’ll find that thinking about what the code does will often help you stream line as you discover flaws in your “narrative strategy.”

Yeah, I know, code doesn’t have a narrative strategy, but are you sure? Think about it. There’s an order in which steps must happen, a process, with a defined beginning, middle and end. Use comments to gloss the process. User short descriptive variable names, not, please, Polish variable names, as one programmer I worked with did, unless of course, you’re coding in Poland. I’m not a programmer, but I’ve looked at a lot of code, and worked in a few scripting languages. I usually write some comments first, outlining the basic parts of the routine, to help me organize my thoughts. I learned that from the person who taught me to use my first scripting language, and it does help.