Comments vs. program structure in programming

Given that all I have is about 3 readers (I exaggerate - including you, I really have four), and given how the topics on my blog are generally dull and boring socio-political tomes, I figure I can afford to bore my readers some more and talk about programming.

Here's what I wrote recently in response to Jacob Gabrielson's post which mentioned the relative importance of comments vs. program structure in programming. Jacob wrote:
What matters most to readability is, first, comments, followed by identifier names, followed by there being as little code as possible, followed by program structure.
I seriously disagree with this statement.

I believe that what matters most are first and foremost the identifier names and program structure; good structure includes that there needs to be as little code as possible; then, to the extent that the meaning of the program is still not plainly evident, this needs to be addressed by comments.

Sticking to anecdotal support, I've seen some very thoroughly commented C++ code that had poor structure, poorly chosen identifier names, and was as difficult to understand as reading someone else's disassembly. The comments did help, but they couldn't make up for the filthy program. On the other hand, I've seen some complex C++ code that was very well written and well-structured and so was intelligible even though it had almost no comments. That doesn't mean it couldn't have used some, but my satisfaction was magnitudes greater with the uncommented, well-structured code than with the well-commented, filthy garbage.

Comments don't make up for a lack of program structure and useful identifiers. However, great program structure and great identifiers can make up for a lack of comments to a large extent.

This is why I believe that it's important for a programming language to encourage and support a good programming practice from which the meaning of the program can be understood. To the extent that the programming language cannot capture and express the meaning of the program, it fails in its task, which is to make software easier to create and its maintenance more manageable.

After all, if comments are all it takes to have readable software, you can have comments in the margin of binary-encoded machine code. The whole purpose of programming languages, starting with evocative instruction mnemonics (assembly) and continuing all the way through Fortran and C and Smalltalk and Lisp, is to make programs easier to write and understand.

I would go so far as to say that the whole extent to which a programming language is better than another can be measured in how well it expresses programmer's intent without requiring the use of comments. Comments aren't part of the structure of a programming language; they are a free-form addition that compensates for the lack of it. Comments can be written in any language.

And I could actually rephrase that to say that the extent to which a programmer is better than another can be measured in how well he or she can express the program's intent before resorting to comments. Anyone can wave around in free-form English about the meaning they are intending to express; but not anyone can express that intent concisely through their program. To the extent that the programming language does not permit the expression of your intent - i.e. to the extent that it requires you to remind future maintainers of something instead of expressing it in a way that the compiler can enforce - that is the extent to which the language sucks.


Popular posts from this blog

When monospace fonts aren't: The Unicode character width nightmare

Circumcision as an adult, part 2

Circumcision as an adult, part 1