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.

Cascading Style Sheets

I’ve looked at articles recommending Cascading Style Sheets before, but I’ve always been frustrated by the browser incompatibilities and bugs. For the last month or so I’ve been following css discussions more closely, and I’m going to try using css again. I still don’t quite understand why people hate tables—I find them to be very useful—but the ability to use a style sheet for my sixty-something pages does appeal to me. So I’m taking a closer look.

I’ve found some good resources—this series of Apple tutorials, for one, and WebMonkey’s Style Sheet Guide then there’s Dave Raggett’s guide—and his useful “ccs readiness” checker HTML Tidy (I’m using Terry Teague’s BBTidy BBEdit plug in port). I’ve also found WDG’s Quick Tutorial and the New York Public Library Style Guide helpful, not to mention all the resources at the CSS Pointers Group.

Next of course is xml.