Download PDF version of this article PDF

Readers’ Comments Are Important, Too

Jef Raskin’s article, “Comments Are More Important than Code” (March 2005), made my day! Ideally the comments should outline (in a form clarified by hindsight) the intellectual process that led to the code.

There is an unfortunate metric called source lines of code, or SLOC, by which some managers evaluate their programmers’ productivity. In literature we recognize the superiority of Gray’s “Elegy Written in a Country Churchyard” over an equal number of stanzas by lesser poets. Poets are not evaluated by source lines of poetry (SLOP). I detest budgets for SLOCs per month.

The process of writing comments to explain one’s code often leads to the embarrassing discovery that the computer program as a whole is not well thought out. Better to conceal this fact by comments on minutiae.

David H. Winfield, Gaithersburg, Maryland

I thoroughly enjoyed Jef Raskin’s article on the importance of comments in source code. His perspective on in-line comments was correct; as a result of this article, I am going to track down the Knuth reference.

I fight this battle over source-code comments on a frequent basis in the arena of commercial software development. When leading projects, I find myself having to nearly hit other programmers over the head with a shovel in order to get them to understand the importance of proper comments (and variable naming).

I personally was fortunate to have:

  1. An average memory. Without comments, I would be lost when revisiting my code two to five years later. Thus, I was forced to comment my code well.
  2. A former boss that micromanaged me for several years. During code reviews, he would ask me to reword comments, fix grammar errors, etc. It seemed excessive at the time, but in retrospect, it taught me good habits.

Thanks for the article—it will become must reading here in our development group.

Erik Hoel, Redlands, California

QUEUE EDITORS RESPOND: Jef Raskin died just as this issue was about to go to press. Widely recognized as the “father of the Macintosh,” Jef made a difference in both the computing community and the world beyond. Here at Queue, though, he’ll be remembered best for his observant eye, his keen wit, and his unfailing professionalism.

APL = A Possible Lingua Franca?

In reference to Stan Kelly-Bootle’s “Linguae Francae” (December/January 2004-2005), I’d like to see these comments in the context of APL. APL lets one create a prototype, a testing base, and an ongoing useful program. Also, APL is self-defining. If you want to know what a program means, that boils down to what it does; since it is interpretive, you can excise any part of it until you do understand it. The specification of the entire program is the program itself.

Finally, since it is a symbolic language, it is (mostly) divorced from natural languages (NLs) and is readable and writable by our Russian colleagues near Moscow, as well as by us.

Georges Brigham, New Canaan, Connecticut

STAN KELLY-BOOTLE RESPONDS: I do agree that APL, and its successor J, eases some of the problems I discussed in my broad-brushed article. We are still grieving the loss last October of APL inventor Ken Iverson, with whom I have shared several conference panels over the years. The conciseness and elegance of APL is quite remarkable considering that it emerged so early in the HOPL (history of programming languages) saga. Indeed, Ken devised it to describe symbolically the logical processes and architecture of the IBM 360. Whence, I suppose, to those who master its rather “arcane syntax,” there is this intense feeling of direct control of the algorithms not found in other interpreted programming languages.

Yet, yet... those arrays (and in J, the other “parts of speech”) need to be named, and without NL, it’s not easy to discuss exactly what their contents stand for. So, we are left with the nagging thought that any purely “formal” system of symbols and operators is fine for “pure” mathematics, yet leaves a gap when you have to plug in kilograms, dollars, and hours-worked in order to solve real-world problems.

We edit letters for content, style, and length.


Originally published in Queue vol. 3, no. 4
see this item in the ACM Digital Library


© ACM, Inc. All Rights Reserved.