Tag: programming

Comments and Clarity: On the Value of Coding

abstract business code coder
Photo by Pixabay on Pexels.com

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


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.

Did you enjoy this post?
If so, consider subscribing to the blog using the form below or clicking on the button below to follow the blog. And consider telling a friend about it. Already a reader or subscriber to the blog? Thanks for reading!

Follow Jamie Todd Rubin on WordPress.com

How to Learn to Write Code in 37 Short Years, Part 2: Adventure Games

Author’s Note: This essay is the second in a series on how I learned to write code. You may want to check out Part 1 if you haven’t already done so.

By the time I got my VIC-20, the computer was already outdated, but I wasn’t complaining. There was only one problem: I didn’t know how to write code. At least, not beyond the few commands I’d learned the previous summer. Moreover, being in a new town, I didn’t know anyone who did know how to program a computer. I was on my own.

What I did, then, was get my hands on some computer magazines. In the 1980s, computer magazines were popular on the magazine shelves, even in the grocery stores. I ignore most stuff in the magazine and focused on the programming samples that they had. I have no memory of what any of these programs did, but I remember some of them spanned multiple pages. I would carefully type these programs into my VIC-20, line numbers and all, and then run them. Often, they’d generate an error as soon as I executed them. Usually, this was because of a typo I’d made. It might seem like an inconsequential thing, but I began to develop a lightning focus for these typos. Today, when I compile something, or run some code I’ve written, and it errors out, I can almost instantly see the problem (forgot a semi-colon at the end of a line; or, a bad indent on a Python script.)

When the programs worked, I was delighted. I also began to experiment. I would change lines of code to see how it changes the program, and slowly I began to deviate from what was on those pages to something different.

This was slow going, made slower by the fact that it took a long time to enter these programs, and the tape drive I had didn’t always save them reliably. If that happened, and I wanted to run the program again, I had to start from scratch. On the downside, this meant a lot of re-entry of code. On the upside, I gained a lot of experience and got more familiar with the code I was entering.

Still, it seemed a slow way to learn. I needed something faster.

Eventually, my VIC-20 was replaced with an Apple IIe, which in turn was replaced by an IBM PC. It was on these two computers that things began to speed up for me. For one thing, both computers used floppy disks instead of tape drives, which made saving the code I typed in much easier. For another thing, I discovered a more practical way to learn to code: by having a specific, concrete goal in mind.

It was on these computers that I first encountered text adventure games. There was the Zork series of game, of course, which had a multiword parser that was almost like typing English sentences. But what grabbed my attention more were the Scott Adams adventure games, which used a simpler 2-word parser. Until i discovered these adventure games, I didn’t even know what the word “parse” meant. It hadn’t come up in any of my English classes. And as it turns out, parsing, is a fundamental operation in both operating systems and computer languages. I didn’t know it at the time, but these adventure games were helping me learn some basics of computer science.

Scott Adams adventure games were like Choose-Your-Own-Adventures, but more elaborate. You were presented with brief descriptions and then presented with a prompt like:

You are standing in a dark room. There is a door on the north side of the room and a hallway to the east. A letter rest on a desk in front of you.

There was a prompt and you could type in two word commands, which would evoke different responses. For instance, you could type:

read letter

which might produce a response: “You don’t have a letter to read.” So you’d type:

get letter

and see: “You pick up the letter from the desk.” Then:

read letter

and see: “Do not open the door. It is booby-trapped.”

The games interested me as a unique form of story-telling. (I was just beginning to write my own stories around this time.) But I was intrigued and fascinated by the mechanics of the game, even more than the storytelling. I tried to imagine what the game looked like inside, like opening up a clock and peering into the elaborate gear-works within. Only, I knew this wasn’t just gears. This code, and I was becoming more familiar with code. It occurred to me that this could be my goal: to learn how to make my own adventure game by learning how these games worked inside.

Right off the bat there were three things about the game that interested me:

  1. How the parser worked.
  2. How the map for the game worked.
  3. How the game knew when things changed within it.

Much later, I realized that through these three interests, I was learning three fundamental concepts about programming:

  1. Parsing and interpreting data.
  2. Storing data and relating data in useful ways.
  3. Managing the “state” of a system.

In almost every piece of software I have created in my professional life, each of these three concepts place a significant role.

I had to really look around to figure this stuff out. There was no Internet at the time. There were bulletin boards, but I didn’t have a modem to connect to any of them, so I was mostly on my own. The computer magazines helped some. Do did the Granada Hills Public Library, where I could go and look at books on computer programming.

I remember I figured out how to write a 2-word parser entirely on my own, in much the way I imagine a person who can’t read music learns to “play by ear.” There was a lot of trial and error, but eventually, I managed to be able to split 2 word input into a “verb” and “noun”. I could compare those to lists and if the entries weren’t in the lists, I could return error messages.

Figuring out the map was much more difficult. Ultimately, I found a way to create a map using BASIC “data” statements. “Data” statements was how data that a program used internally was stored a part of a BASIC program. Imagine an adventure game with 4 rooms. There are 4 cardinal directions that are possible from each room. Suppose you have a map that looks as follows:


Sample adventure game map
Sample adventure game map

The data statement for a map might look something like this:

DATA 1, 'You are standing in room with a door to the north and a hall to the east', 3, 2, 0, 0
DATA 2, 'You have entered a hallway. There is a room to the west.', 0, 0, 0, 1
DATA 3, 'You are in a cave. A door leads south and there is a sldie to the east.', 0, 4, 1, 0
DATA 4, 'You are stuck in a pit at the bottom of a slide.', 0, 0, 0, 0

The first number is the room number as shown on the map. The next item in the statement is a description of the room that is displayed when you enter it. The following four numbers represent the rooms you can get to for each of the cardinal directions, north, east, south, west. So from room number 1, you can get to room number 3 by going north, and room number 2 by going east.

Figuring out the “state” of the game was probably the most difficult. Consider the letter on the desk. If I tried to read the letter without picking it up first, the game would tell me that I didn’t have a letter. But if I picked up the letter, I could read it. The game had to know that I had picked it up before I could read it. Once I picked up the letter, the “state” of the game had changed. But a game could have dozens or hundreds of situations like that. Door that were closed or opened. Lights that were off or on. Puzzles in these text adventures were largely based on the state of the game.

Eventually, I figured this out, too, although it took a little help. For the first, and only time, I enrolled in a class on computer game programming that was being given at California State University Northridge. I think it was a Saturday class through their extension program. I do remember that I was the only “kid” in the class. That class was helpful in that it provided a useful structure for how to think of things like “state”. It also taught me how to create a game where the “monsters” in the game were taught to find you, regardless of your position in the game map. (Much later, I realized this was an algorithm, but I didn’t know it then.)

I kept at it. I created my own adventure games which, in their look and feel, seemed indistinguishable from Scott Adams adventure games. It was only in their story-telling ability that they flagged. I tried to make my games too complex, with maps with a hundred rooms instead of a few dozen. I was less interested in the storytelling and more interested in the mechanics. The more code I wrote the better I got, but it was almost always off-the-cuff. They were also always plain text games. I felt I needed to expand my wings a bit.

I began looking for practical applications for my programming, instead of just building something to see if I could. One thing I coveted was Microsoft Flight Simulator, mainly because I’d always wanted to be a pilot, and flight simulator was about as close as I could get as a teenager.

The opportunity came as part of a project in a computer programming class I took in either eighth or ninth grade. Don McLish was our computer teacher and our project was to built something using the concepts we had learned. I built a flight simulator. It was a fairly simple thing. I think there was a single instrument, and line that represented the “horizon” out the window. But it moved the way it should as the plane steered through the air. I remember it requiring programming using some trigonometry, which I was taking in math at the time. It impressed the teacher enough for him to sent a note home to my folks.

This encouraged me, and despite the occasional comments that I was “spending a lot of time” on the computer, I continued to practice writing code, more and more looking for practical applications. In high school, worked in a local pharmacy and was impressed by the software the pharmacist used to manage his customer database. I went home and tried to mock-up my own version of that software as a kind of personal “rolodex” program on the IBM PC that I had. It worked so well that I used that program for several years, including my first few years in college.

In college, things slowed down a bit as I was focused on classes and my interactions with computers was mostly for typing up notes and papers. But two things took place in college which would have a big impact on me and my programming.

The first was a computer class that I took with one of my roommates. I think we learned to program in Pascal, a teaching language. That class made me realize that most computer languages were more alike than they were different. It wasn’t a big deal for me to go from BASIC to Pascal once you knew the subtle differences. We also used NeXT workstations our labs for that class, and I was impressed by the NeXT, which was Unix-based underneath. It was a fleeting thing, because the class was just one quarter, but I didn’t forget the NeXT or that initial introduction to Unix.

The other thing that took place was a promotion I got. I’d been working in the dorm cafeterias for my entire time in college. I’d started in the dishroom (which I enjoyed) and worked my way up to a supervisor, and then, in my senior year, into the business office, where I ended up spending the year writing computer programs to automate the cafeteria budgeting process in Microsoft Excel. I was now being paid to write computer code, and as much as I enjoyed working in the dishroom, I enjoyed this work a lot more.

How to Learn to Write Code in 37 Short Years, Part 1: Hello World!

Recently, I passed a personal milestone. It is an arbitrary milestone, one for which I am the sole judge, but it is one that has been 37 years in the making. I have been a professional developer (coder) for about 27 years now. In that time, I’ve generally had no problem considering myself a professional. No impostor syndrome there. But there is one thing from which I have refrained referring to myself: an expert.

Until now, that is. Now, after 37 years of learning how to write code, I think I do it at a level which could be considered expert. Perhaps even by someone other than myself.

“Developer” sounds a little phony to me. I’ve read about people who are developers (land developers) and I’ve never really been clear on what that entails. I prefer referring to myself as a (professional–now expert) “coder.” It’s less formal, but despite its reputation, I’ve always felt there is something informal about coding. I’ve been wary of the term “expert.” It seems to me that it is overused to such an extent as to water down the meaning. I’ve seen all kinds of books about becoming an “expert” this or that in 30 days. Maybe I’m just bitter at being a slow-learner but it took me 37 years before I finally considered myself an “expert.”

One thing I don’t consider myself is a software engineer. An engineer has a specific meaning in my mind, and entails a certain kind of formal education in software development that I lack. I am not an engineer. I am immediately suspect when I see “software engineer” on a resume when I don’t see an engineering degree along with it. I’m much less suspect if I see “coder.”

I tend to be a slow-learner, perhaps because I dive in head-first and try everything at once. I’ve written about how it took me 14 years of writing and submitting stories, collecting more than a hundred rejection slips before selling my first story. It took me 11 years of teaching myself to write code, before I landed my first (and so far, only) professional gig. In that regard, it only took another quarter century or so before I felt I could call myself an expert.

So how does one learn to write code in 37 short years? For me, it began with hangman, and WarGames.

The first computer I ever saw was a Commodore VIC-20. I saw it in my 5th grade math class sometime in the late winter or early spring of 1983. There are exactly 3 things that I remember from that math class. First, our teacher was missing part of a finger. Second, one of our lessons was learning to read the stock pages in The Providence Journal. Third, was the Commodore VIC-20.

There was no math associated with our introduction to that computer. I remember it was wheeled into the classroom, connected to a television set. We spent the class using the VIC-20 to play Hangman. I didn’t see a line of code during that introduction, but I was intrigued by what I saw.

The summer of 1983 was my last on the east coast before I moved with my family to Los Angeles. It was the summer that WarGames with Matthew Broderick and Ally Sheedy made its debut. I saw the movie in New York with my cousins. I don’t recall the movie making much of an impression one way or another at the time. What I remember most about that day was going back to my cousin’s house after the movie, and being introduced to his Timex Sinclair 1000. It was the first computer I ever laid my own hands on.

My cousin turned on the computer and showed my how to write a simple program in BASIC. The program was:

20 GOTO 10

The program doesn’t do much, but something in my brain clicked. It was like I understood the concept of programming in that instant. With a finite (even small) set of instructions, and some basic logic, you could make the computer do all kinds of things.

That evening, we made the computer break into a top secret installation. We didn’t have a modem or any kind of connection to the outside world. But using our memories of WarGames, and my quick absorption of BASIC, we wrote a program that made it seem like we were hacking into some secret computer system. I can’t remember what I program looked like, but it was probably something like this:

20 PRINT "Enter your password:"
30 INPUT x
40 IF x = "password" THEN GOTO 50 ELSE GOTO 60
50 PRINT "Welcome to Global Thermonuclear War"
60 PRINT "Wrong password"

Yeah, we didn’t have the logic quite right, but the idea that through some simple instructions you could make the computer to all kinds of things was a revelation for me.

At the end of that summer, we said goodbye to the east coast, and hello to Los Angeles. Any move is tough on an 11-year old, but moving across the country, away from all of your friends is particularly tough. But I had something cooking in my mind that I was looking forward to. I was going to figure out a way to get my own computer. I didn’t particularly like the keyboad on the Timex computer. What I had in mind was the VIC-20 I’d seen in my 5th grade math class. I thought about it so often that I’d dream about it. I remember a couple of occasions that I dreamed I’d gotten a VIC-20. I was so excited! Then I’d wake up, uncertain at first if it had been a dream, and then, crestfallen, that it had.

Until one day, I had one! My very own Commodore VIC-20. And it came with a tape drive! My real coding experience was about to begin…