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.

Edward Feser's road from atheism to theism

I was reading a blog post by philosophy professor Edward Feser describing his conversion from atheism to theism. It is interesting to note the reasons that led to his change of mind:

• "The first of them had to do instead with the philosophy of language and logic. . . As the arguments sank in over the course of months and years, I came to see that existing naturalistic accounts of language and meaning were no good."
• "At first, and like so many undergraduate philosophy majors, I took the materialist line for granted.  Mental activity was just brain activity.  What could be more obvious?  But reading John Searle’s The Rediscovery of the Mind destroyed this illusion, and convinced me that the standard materialist theories were all hopeless."
• "Most importantly, though, Lockwood’s book introduced me to Bertrand Russell’s later views on these issues, which would have a major influence on my thinking ever afterward.  Russell emphasized that physics really gives us very little knowledge of the material world.  In particular, it gives us knowledge of its abstract structure, of what can be captured in equations and the like.  But it gives us no knowledge of the intrinsic nature of matter, of the concrete reality that fleshes out the abstract structure.  Introspection, by contrast, gives us direct knowledge of our thoughts and experiences.  The upshot is that it is matter, and not mind, that is the really problematic side of the mind-body problem."
• "Second, a complete naturalistic explanation of intentionality is impossible."
• "It was also while still a naturalist that I first started to take a serious interest in Aristotelianism, though at the time that interest had to do with ethics rather than metaphysics. . . One consequence of this was that I always took teleology seriously, because it was so clearly evident a feature of ordinary practical reasoning."
• "As I argue in The Last Superstition, many of the so-called “traditional” problems of philosophy are really just artifacts of the anti-Scholastic revolution of the moderns."
• "Fregean and related arguments had gotten me to take very seriously the idea that something like Platonic realism might be true.  (I would later see that Aristotelian realism was in fact the right way to go, but the basic anti-naturalistic move had been made.)  The arguments of Searle and others had shown that existing versions of materialism were no good.  Russellian arguments had shown that modern science and philosophy had no clear idea of what matter was in the first place.  Whatever it was supposed to be, though, it seemed it was not something to which one could assimilate mind, at least not if one wanted to avoid panpsychism.  Naturalism came to seem mysterious at best.  Meanwhile, Aristotelian ideas had a certain plausibility.  All that was needed was some systematic alternative to naturalism."
• "Then there was Aquinas. . . It was all very strange.  Aquinas’s arguments had a certain power when all of this metaphysical background was taken account of.  And there was a certain plausibility to the metaphysics."
• "The only reason for not taking Aquinas and similar thinkers seriously seemed to be that most other academic philosophers weren’t taking them seriously.  And yet as I had come to learn, many of them didn’t even understand Aquinas and Co. in the first place, and their own naturalism was riddled with problems."
• "As I taught and thought about the arguments for God’s existence, and in particular the cosmological argument, I went from thinking “These arguments are no good” to thinking “These arguments are a little better than they are given credit for” and then to “These arguments are actually kind of interesting.”  Eventually it hit me: “Oh my goodness, these arguments are right after all!”"

Favorite things to do

If you ever wonder what your favorite things to do are, or what's the best way to spend your leisure time, may I offer these wonderful suggestions taken from an unlikely source—the section on the Sunday rest from the Catechism of the Catholic Church:

• Family. “Christians will also sanctify Sunday by devoting time and care to their families and relatives, often difficult to do on other days of the week.”
• Good works. “Sunday is traditionally consecrated by Christian piety to good works and humble service of the sick, the infirm, and the elderly.”
• Prayer. “On Sundays and other holy days of obligation, the faithful are to refrain from engaging in work or activities that hinder the worship owed to God, the joy proper to the Lord's Day, the performance of the works of mercy, and the appropriate relaxation of mind and body.”
• Study. “Sunday is a time for reflection, silence, cultivation of the mind, and meditation which furthers the growth of the Christian interior life.

My personal favorite is Study. Here are some of the resources that I like to immerse myself in on those rare occasions that I have blocks of free time:

• Music: Listen. Music appreciation course CDs and textbook.
• Philosophy: Aristotle: the desire to understand.
• Poetry: The New Penguin Book of English Verse. Unlike most poetry anthologies which are organized by author, this organizes the poems by date of composition. So it feels like a kind of time machine.
• Religion: Introduction to the Devout Life. St. Francis de Sales.
• Art: The Story of Art. Generously illustrated story of the artistic masterpieces of the Western world.