Daniel Pitts’ Tech Blog

When we write, we seek an elegance in our expression. We intend the writing to be read either by ourselves or others. Stylistic devices help us convey our intent. Rewriting and moving parts around comes naturally, if we think it’s better.

There are also different levels of writing. I feel we label them backwards, when we say “reading level”. Some writings are much more difficult to read, due to the structure used or the difficulty encountered while trying to express your intent with the written language. The product of some authors is easier to read because it is better organized in both its structure and expressions.

It can be difficult to express certain things unless we assume a reading level of our audience, and by all rights we should assume the audience is capable of understanding, provided the structure is as elegant as possible.

Usually, the same meaning can be expressed in many different ways. Sometimes we strive to find a concise expression, even if that conciseness of expression increases the reading level.

You might feel like asking me “So, what’s with the essay on writing? Isn’t this a Tech Blog? It says so right in the title!” I never said I was talking about writing in English. All of those statements apply to writing a program as much as (if not more than) writing an essay. Why is it that we spend so much time teaching programmers-to-be about syntax and making the compiler understand, and so little time on teaching them how to make an understandable and expressive source file for humans?

We all look back on our early projects and thing WTF was I thinking? Even our comments were unhelpful. /* this statement tells the readers that the comments didn’t help */

For people who are passionate about developing software, the realization comes eventually that code can be expressive without the need for comments. Comments become useful only to explain justification for choosing an approach over another, instead of reiterating what the code says it does. Breaking a procedure down into its component parts and naming them appropriately not only allows a person to read the code in a more natural manor, it helps the original author not repeat themselves.

It could be that part of the problem is that text books use comments to explain syntax to the students.

/* The following line assigns the value “foo” to the variable bar. */

This may be useful as a teaching tool, but when you’re writing software in a professional environment, you’re (usually) not trying to teach your colleagues the syntax of that particular programming language. Computer Science teachers often compound the problem be setting a comment quota. The only time I felt that was at all justified was my assembly language teacher, who required more than one comment per line of actual code.

The moral of the story? Separate the teaching of syntax and the teaching of how to write a program. Teach people that using a meaning name can be more powerful than two comments (one at the call, and the other at the definition). Help people understand that your writing isn’t meant only for the compiler, but as much (if not more) for the human.

Make the world a better place. If you feel the need to comment on what a piece of code does, turn it into a function/method/procedure call whose name implies your would-be comment. Do this even for conditions. “if (cans * pricePerCan < goal)” can be rewritten as “if (belowPriceGoalForCans())”.