Comments and Clarity: On the Value of Coding

Over on his blog, The Waiter’s Pad, Mike Dariano asks, “How much coding do you really need?” It is an interesting thought piece. He observes that,

What we really mean when we say, “people should know how to code” is that people should be able to use tools to deliver value.

I’ve been coding for most of my life. I saw my first BASIC on a Timex Sinclair. I loved the logic of coding. A year or two later, I got a Commodore VIC-20 and had everything I needed. It took a while before I mastered BASIC, and moved onto other languages, but I did, and today, there are a dozen languages that I can code in comfortably.

After reading Mike’s piece, I thought about what he said about what we really mean when we say people should know how to code. While I agree that it often means that people should be capable of using tools that deliver value, it is the question of value that stuck with me. What value has knowing how to code produced for me? It breaks down into two areas: practical value, and what I call “comments and clarity.”

The practical value of coding

Knowing how to code got me out of the dish room in college and into the cafeteria office, where I began writing programs to help the staff manage the cafeteria budget. That, in turn, led a job not long after graduating–a job and company that I am still with nearly 27 years later. So, yeah, knowing how to code got me a career, and there is obvious value in that. What else? If I have a problem to solve, I can often solve it though code. A few examples:

• When we were looking for a house, I wrote code that would pull data from listings and filter the list down to the most likely candidates. Instead of manually searching through listings, I had the code do it for me, and we just had to look at the results.
• When I wanted a better way to track my writing, I wrote my Google Docs Writing Tracker, which worked great for me (and quite a few others) for many years.
• In order to automate my daily notes in Obsidian, I wrote a script to make it happen and save me a bunch of time.
• I’ve written countless scripts to automate the repetitive tasks in my life. Some of these are a few lines of code, others are thousands. Together they free up time so that I can focus on the things that are more important to me.

The value of comments and clarity

Comments

It is incredibly difficult for me to hold everything that a big piece of software is doing in my head at one time. This is why comments exist in code. I use comments in code to remind myself why I did something in a certain way, or how a particular function works, or sometimes just a reminder to clean something up later. I’ve even written comments critical of my own code: “This is an ugly hack, but it works” used to be a standard refrain of mine.

Commenting helps me think about there things: (1) how the code works, (2) why it works the way it does, and (3) how it could be improved. Comments are both descriptive and introspective. They are a form of written observation. I have applied this concept to my life more generally:

• I’ve kept a journal since 1996, which is just another form of commenting, both descriptive and introspective, and one in which I seek ways to improve.
• In my day job, I am known for having exhaustive notes and documentation on just about everything I do: another form of commenting.
• I’m rarely without a Field Notes notebook in my pocket to jot down comments and stray thought so that I don’t lose them.

Commenting helps me to understand myself and what is happening around me. It preserves memory, while providing a space to “show my work” and learn from my experience. My comments–journal entries, daily notes, Field Notes notebooks–provide a baseline from which I can look back or ahead for improvement, failures, and learning.

Clarity of thought

A program compiles or it doesn’t. A semicolon in the wrong place, a mistyped variable, a greater than sign instead of a less than sign, a problem with the logic of a decision tree, a faulty data structure–any of these things can prevent a program from doing what it is supposed to. Repeated attention to the strict and unforgiving nature of coding helped to build a clarity muscle, one that strengthens my clarity of thought.

To me, clarity of thought is the ability to focus in on what matters in a particular situation. It is the ability to tune out the pieces that don’t play a role, and look more closely at those that do. It means to look at them from every angle, and then ask, are there other angles I haven’t considered. This is helpful in just about everything I do. What clarity of thought is not, is a Vulcan-like adherence to pure logic. It is not emotionless.

Nowhere has clarity of thought expressed itself more than in my writing. While writing fiction has always been a difficult, often tedious task for me, writing nonfiction rarely is. I began writing the same time I began coding. In high school and college I never had trouble with papers. That clarity muscle that coding helped develop seemed to do the job of organizing the writing for me. In my nonfiction writing, articles I’ve sold, and even here on the blog, I like to think that my style is clear and easy to follow. That clarity comes from the clarity of thought that coding nurtured.

(Often times this clarity comes after seeing a first draft. Case in point: the first draft of this post was 1,700 words and not as well organized. Upon reading it, I cut and restructured it, and hopefully, made it better and more clear than it was in its original form.)

It is for the practical benefits, as well as the benefit of clarity of thought that I have encouraged my own kids to learn how to code. Or at least, try it out and see if they like it.

Clarity of thought has been a good trait for problem-solving. It has also been honed enough to know when not to try to solve a problem. As Mike says in his post,

Rather than “learn to code” we should focus on “learn to solve problems”. Many of those problems will require tools. Some of those tools will be code.

For me, learning to code was the tool I used to learn to solve problems. It led to useful introspection and analysis (the commenting) and a gradual improvement in clarity of thought, both of which have been invaluable tools for problem-solving for me over the years, more than learning to code ever was.

P.S.: Seriously, go and check out Mike’s blog, The Waiter’s Pad. It is excellent.