JWZ on commenting code

I love this exchange between Peter Seibel and Jamie Zawinski from the book Coders at Work. It captures what I like about well-documented code.

Seibel: Earlier you said something about writing code in order to make it easier to read, which ties into maintenance. What are the characteristics that make code easier to read?

Zawinski: Well, comments obviously. Writing down what the assumptions are and what this does. If it's building up a data structure, describing the layout of it. A lot of times I find that pretty helpful. Especially in writing Perl code when it's like, uh, well, it's a hash table and values are bunch of references to lists, because the data structures in Perl are just nuts. Do I need a right arrow here to get to this? I find examples like that to be helpful.

I always wish people would comment more, though the thing that makes me cringe is when the comment is the name of the function rephrased. Function's called push_stack and the comment says, This pushes to the stack. Thank you.

You've got to say in the comment something that's not there already. What's it for? Either a higher-level or a lower-level description, depending on what's most important. Sometimes the most important thing is, what is this for? Why would I use it? And sometimes the most important thing is, what's the range of inputs that this expects?

Long variable names. I m not a fan of Hungarian notation, but I think using actual English words to describe things, except for loop iterators, where it's obvious. Just as much verbosity as possible, I guess.

comments powered by Disqus

Did you know?

I'm a software engineering consultant. This means I can help your company with your software engineering needs:

  • providing temporary manpower for short-staffed software projects

  • helping new software projects get off to a good architectural start

  • improving the performance and reliability of old, legacy software systems

  • doing an important investigation or small project that you've always wanted to do but haven't had time for

Since 1999, I have done software engineering projects for the Canadian government, for Silicon Valley startups, and for established Bay Area companies, for small companies and medium-sized companies, for successful commercial projects and open-source projects. 

Currently accepting small projects. If you have one, email or call me.