Like a Sentence
Writing code can be great, and when we write it, even though there is not usually a spectator sitting with us, we have to think of the audience. Assume that there is someone outside of us, who is picking up our code after we’re done (or gone). In general it is important that we foster the idea of having our code communicate strongly with the reader. So, when teaching people a programming language, start with the best possible analogy and train students with what they should already know: language.
Grammar: Syntax
Often when people start learning or thinking how to code, they only think of the end result. Whether we write a novella or novel, it is important to put things in ways that not only we understand, but for whoever picks up our book and begins to read it later. Sometimes the person picking up that book is us (god dammit, who wrote this? …oh it was me…). A lot of times that person is your coworker or even your future replacement.
That is why it is imperative that when we write, we assume that someone is going to pick up our code, dust it off and be able to understand it; we need to practice coding empathy. Our code can tell a story. This is to say we should not just “let the code speak for itself”. We also need at times to provide proper context to set the scene (specs and documentation) and explain nonsensical business logic (that made sense in someone’s mind).
Whatever language, the syntax remains stoic. The syntactic sugar that holds everything together and helps you write, and it is up to you to provide clearly defined nouns, verbs and conjunctions.
Editor (the person not the thing): Linter
Following specific syntax is pretty much unavoidable in programming, so there is usually not much to discuss here. Some languages are more strict than others, and people have different rules for writing (in their opinion) correct and clean code.
Whatever you decide (or was decided for you by your “Editor”), it is important to adhere to the rules set down. Linters can take it a step further and be more opinionated on how you write code. These guard rails are a good step in making sure your stories make sense to the reader.
Nouns: Variables + Data Structures
About the most worthless word in the English is thing. It is a word that can mean pretty much everything, anything, and nothing. That’s why when we want to be effective communicators, we should toss that word into the rubbish bin in our minds.
x, y, z, i, j, k, foo, bar… the hallmarks of someone learning a new language. And, about the only acceptable time to use these variable names (unless you’re using them in a coordinate system). They are the things of the programming world, so throw them away early. Make sure your variables: say their name, state their use, or define their existence. Naming something can sometimes be hard, but it also trains us to be precise in our language and impactful in our speech. With a sprinkling of adjectives (pseudo-properties) we can hopefully add some additional context or meaning to our words.
Sometimes nouns are not completely analogous to variables, and are at times more closely related to data structure or instances. Variables can actually contain references to whole ideas and in some languages contain references to functions.
Possessives: Properties
Common in language is the idea of ownership. These correlate with properties, getters and setters for objects (e.g. User.height, User.homeAddress).
Verbs: Functions
If nouns are the fundamental building blocks for holding meaning, our functions fill the role of performing tangible concrete actions. Functions or methods often complete a simple sentence in our code. Modifying or changing our nouns, picking them up, putting them down, throwing them around a bit, roughing them up a bit (pass by reference), or leaving them alone (passing by value).
Copula: Assignments
What it be: These are special little verbs or linking verbs, essentially they assign value. Logical assignment operators such as = we can read as is.
Conjunctions: Logic
Ok kids, we’re also learning about conjunction logic. Without “if, not, but, for, and, or”… we would be truly lost. These words represent the conditions and decisions we tell our reader what will happen or when. These conjunctions help you in determining the “choose your own adventure” path your application takes.
Our logic can get seriously complicated, so it is important to realize that we need to atomize our conditions so they read better in our operations.
Manicules: Comments ☟
Sometimes it’s polite to point. The manicule is one tiny hand and dates back in usage to the scribal tradition of the medieval and Renaissance times, placing them in the margins of the pages to point out alterations or make notes. Today people go crazy with brain-numbingly scented high-lighters.
In code, comments serve a similar purpose. When we have to write something weird we need to let others know why we wrote something weird, being weird or due to time — cutting all kinds of corners. Code is better when we let people know about our weirdness; we need to own our weirdness, otherwise we will end up getting labeled as a pain in the ass. Comments help us point out exceptions and explain to others when our assumptions may go off the rails, or even provide notes when `TODO or FIXME` some thing or -task- later.
Note: Something akin to FIXME is fine in drafts (i.e. scripts) not so good for code making its way into production. A literal example I have seen 🤦♀️:
// *Username*: do something in hereObviously if you need so much explanation you might have a different problem, and it might be time to rewrite that section or provide supplemental documentation (your code’s appendix).
Extra advice
- Pair programming can help you in other ways besides sharing knowledge. It forces the writers into a mindset of creating code that is understandable because you have to communicate more strongly, and helps create an audience where feedback can point out confusing tidbits more quickly.
- Be positive, i.e. don’t be so damn negative all the time. Talk about existence, not non-existence. Double, triple negatives are hard in regular conversation, why would they be easy to read in code.
- Spelling matters. Typos linger and improper spellings can last forever and can be difficult to fix. For example, API methods with typos mean they are now built into the contract (sigh…, ugh…).
- This perspective also has utility in other areas of development: creating design systems, component libraries.
