Writing for Machines

I find beauty in Programming Languages. I believe this to be an aspect of programming that is rarely shared outside of “techie” circles. This is my attempt to share that beauty with a non-technical audience.

I'll be mapping ideas of Programming Language to spoken language concepts.

There are many different Programming Languages, and they all have different vocabulary and grammar and quirks. We're going to be reading and writing in Python. Python is a “real serious” language used by many companies that you’ve heard of — Google, Facebook, Netflix to name a few. I like Python and I think it's particularly suited towards illustrating my points.

At the end of this guide you won't have a program that uses the latest buzzwords floating around Silicon Valley. What you will have at the end of this guide are the building blocks required to understand how programs are written.

To get started we need to get acquainted with the grammar and “vocabulary” of Python.

There is a Python interpreter that is embedded below. Type whatever you please into it and press enter (you're probably going to get an error, don't worry about that!). The enter key prompts Python to read and interpret your code. Python reads and interprets each line you write left to right, top to bottom. Try typing stuff into the interpreter and watch what happens. Python will spew errors for statements it doesn't understand, but no worry! Keep pressing enter to get the prompt again.

You’ve probably heard the phrase that a computer is just zeros and ones, and there is truth to that. The physical circuits attached to your keyboard are just wires dancing with 5V (one) and 0V (zero). Programming languages are tools created by people to that translate our written instructions into the 0’s and 1’s that computers understand. Python is what’s called an “interpreter”. Python interprets our code, reading it from top to bottom, left to right and transcribes what we write into the 0’s and 1’s that your computer understands.

Let’s get into how to write Python. Python comes with a long list of words built into its language. For example, Python understands numbers. Try typing numbers and pressing enter. Python will echo your statement, and it won't print any errors.

The same goes for text that is between quotes like “roses are red”, Python understands that literal text.

Now we’re going to delve into something that’s common in the programming world. They’re called “variables”. Variables are the start of you creating your own “words”.

Try:

money # Ahh an error!

Python doesn't know what money means. It's not one of the built in words.

money = 1000000

Here you’re defining your own word, in this case a noun called “money” (monkey is an equally valid name to give this variable) and you’re setting it equal to 1 million.

Now that you’ve defined your variable, ask Python what it means. (The same command that you had run previously.)

Try:

money

Python tells you that “money” now means 100000. This is the first example of you being able to create names for things and defining what they mean in this language.

You can think of variables as the “nouns” of the language.

In Python there are also “verbs” which do things to nouns. Python also has a list of verbs built into the language that it understands. They require some special grammar to use.

Try out this statement then we'll break it down.

sorted('diaper')

Cool! You see, Python did something! You gave it a complete statement and it was able to parse and perform what you requested.

“sorted” is the verb, 'diaper' is the noun. The grammar of Python is much more rigid than that of spoken languages. The quotes give away that 'diaper' is the noun. The parens give away the verb, in this case “sorted”. Verbs act on nouns, you put the target of the action of the verb into the parenthesis. If your verb acts on multiple nouns you can separate the nouns with commas.

Try:

add(5000, 1.2, 30)

An interesting bit to take note of is that some verbs have a result for their actions. In this case 5031.2

Try:

total = add(5000, 1.2, 30)
total

Now we’re really starting to play with language. Here we’ve defined our own noun total and defined it to be the addition of 5000, 1.2 and 30. This act of building together smaller ideas into bigger ones is the crux of writing programs. Figuring out the verbs and nouns that you need to get a larger task done.

Time for a small aside... As with any language, there are some quirks that are a little out of place but they exist because they make expressing ideas easier.

For example “+, -, /, *” are all verbs in Python. But they don't have parentheses! The nouns they act on look totally out of place!

Try: 5000 + 1.2 + 30

It works! But the rules say that it shouldn’t! But it’s nice that it does, right? Python's grammar does allow expressing math this way because many argue that it's easier to read than add(5000, 1.2, 30) even if it does break the typical “rules” of grammar. In fact there are other Programming Languages that instead use the grammar (+ 5000 1.2 30) so as not to introduce quirk and preserve the “purity” of their language.

Just like how we can define our own nouns, Python also lets you define your own “verbs” these are called functions.

Try: def double(num): return num + num

double(15)
more_money = double(money)
more_money

There is a lot happening here, but we’re going to go through it step-by-step, top to bottom, left to right.

Here we’re seeing Python’s rules of grammar for defining your own verbs. The “def” is short for “define”, defining your own verbs is so common in programming that even the word “define” was deemed to be too long to type out every time. “double” is the name that I chose for my own verb because I think that it’s a good name for what my verb does. The parens make a reappearance, once again we’re defining the noun that we want to act on, calling it “number” (I picked the name number, because I think that it’s a decent name for what we’re acting on…). “return” is how we send back the noun. We’re sending back “num” added with itself.

Time for another small aside… What’s interesting here is that Programming Languages give you the tools to define your own words and grow the language you’re working with. You’re expected to work within the rules of the grammar to expand the vocabulary to better express your task at hand.

Typically in spoken language, I feel that the reverse is true-- the rules of grammar can be played with and readers can follow along, but if you make up a word out of thin air, you’ll get funny looks.

Because engineers typically work in a team, it’s not just machines that are reading your code, it’s also the humans that are building features with you. Your code’s intent needs to be clear and understandable for both the machine and the human. A huge part of my day job is figuring out which names are best suited to describe what I’m building. Defining nouns and verbs that describe the steps required to complete a task.

But even when you make you intent perfectly clear in your own eyes, writers looking to use the code you’ve defined will always find a way to surprise you.

For example, try out. What do you expect to happen? double('foo')

It actually… works? kinda? Of all the error messages that you’ve seen spewing from Python. Isn’t it funny that this “worked” just fine? People coming up with ways of using code that is outside the original author’s intent happens all of the time in programming. Other languages don’t allow such freedom and provide safeguards around this kind of thing. If you’re doing serious business programming then it might make sense to use a language that is a bit less permissive with its interpretations. But personally, for the purpose of learning programming, I like how this language has wiggle room.

Programming Languages have one more slight over Spoken Language…

Try:

x = 0
while x < 10:
  x = x + 1
  print('Here I go again! ' + x)
  x

Woah, what happened here? What happened to “Python reads your code top to bottom, left to right?” Yeah sorry about that, turns out that’s only mostly true. And it’s really quite important that it’s not totally true, this is a key property to making Programming Languages useful.

So the “grammar” here is that Python will keep on re-executing statements until some condition is reached. The code above can be read as “while x is less than 10 do…” Python reads the “while” and then it understand that a condition needs to follow. In this case, the condition that x < 10. Python executes that and indeed sees that x (which was set to 0) is less than 10. Python then executes all of the statements that are indented. x gets redefined to be 1 bigger than it was before, and we’re printing out a message.

About that print... Oh, print, we haven’t seen that before have we? Well, we already know the grammar for that. It must be a verb and it’s acting on the noun exists in the parenthesis.. Just like spoken languages, print is a term that’s a relic from the past. Print harks back to the days when computers interpreted holes punched through paper as a computer program, and would physically “print” out the results to a sheet of paper. Print is still used as the canonical phrase for displaying output across many different Programming Languages.

Back to while… Now that Python has executed all of the indented statements, Python checks the condition again. This time x is 1. But that’s still less than 10. So Python keeps going through the loop “while x is less than 10”. That’s why we see all of those print statements, they keep happening until the condition is no longer met.

So this is different. I don’t really know how to map this into Spoken Language. We’re changing the order in which Python reads its statements. And this is really powerful. This ability to jump around statements based on some condition is a key part of defines a computer.

Also, now that we’ve mastered the “while” loop, this new statement should be a no-brainer:

if x > 0:
  print('X is less than 0')

“if” tells python to only execute the indented code if the statement is true.

Alright let's re-group. That was a lot.

But, it’s an entire language! With these rules you can build some pretty cool things. As simple as this may seem we have the basic grammar down for writing Python programs. Python has many more built-in functions (verbs) and grammar constructs to help express your ideas, but we’ve actually covered the basic rules.

And it’s with these small basic rules that the computer you’re reading this guide is defined. Over the years programmers built and combined programs to build bigger and bigger programs. Platforms were built to help programmers share their “writing”. Until we finally got to web search, photo sharing and this very guide.

Check out this these programs, can you guess what they do?

def fibbonocci(how_many):
  if how_many == 0:
    return 0
  elif how_many == 1:
    return 1
  else:
    return fibbonocci(how_many - 1) + fibbonocci(how_many - 2)

def scream(text):
  return text.upper() + '!!!'

def star(how_big):
  i = 1
  while i <= how_big:
    print(' '.join(['*'] * i))
    i = i + 1

I hope that you have a better understanding about Programming Languages and how they relate to Spoken Languages. I hope that I’ve made the argument that programming allows for creativity around introducing new terms and phrases to make it clear to a reader (machine or human!) what the intent is. And I hope that I’ve sparked your interest in programming.

If you like these topics and want to hear a better form of this by someone way smarter than me in video form checkout: https://www.youtube.com/watch?v=_ahvzDzKdB0

GOB is also a fantastic book that plays with these ideas much better than I can.