This is a recap of a Lightning Talk given by Senior Software Engineer Alex Ball at WordPress’s 2019 WordCamp US in St. Louis.
Let’s talk about coding like a writer.
It may sound like a recipe for disaster at first, but it’s actually a helpful approach to WordPress development. I know there are people who come to WordCamp, who work with WordPress on a regular basis, who do not have a background in computer science.
I’m one of those people, too. I spent the first eight years of my career working at Baltimore Magazine as a writer and a copy editor.
And then one day I found myself taking over the website, and I had to teach myself how to code.
What I have learned, and what I want to share with you is that your background in writing can provide you with familiarity with coding, and help build your coding confidence.
So for those of you are non-technical people who need to be able to do some HTML work on your company’s website or apps, or for those of you who also want to become more technical, or even for those of you who are already technical but want to see it from a different perspective, we’re going to talk about coding like a writer.
Let’s start with some of the principles we have when writing.
Writing Principles
Punctuation saves lives
We’ve all heard this. Every proofreader who has ever lived has uttered this phrase. Why is this important in coding? Take a look at the example below.
require_once( ABSPATH . 'super-important-file.php' );
Even in this simple example, there’s a lot of punctuation. If it’s missing the semicolon at the end, your app is not going to run.
Punctuation is incredibly important in our coding.
And we know from our writing that punctuation is important, because “Let’s eat, Grandma!” is very different from “Let’s eat Grandma!”
And that’s bad. That’s as bad as your app not running. Maybe worse.
Don’t mix metaphors
Another thing to avoid is mixing up your metaphors.
The home-run hitter scored a touchdown when the chips were down.
This is a mess. It’s confusing, and as a result, your message gets lost.
Just as you want to separate your metaphors when writing, you want to separate your concerns to avoid confusion when coding.
That means in your WordPress development, you want to keep your functions in functions files and out of your template files.
Good functions files still give you a chance to write something in your own words by using comments. All of your functions should have comments because they will explain exactly what you mean. They give context to others joining the project and help them know the purpose of the function.
Clear instructions
Some of you reading this may have DIY or crafting or cooking websites built with WordPress.
And what are you doing on a regular basis there? You're providing things like recipes, which are lists of ingredients and followed by instructions for assembling the finished product.
In those recipes, you are (I hope) clear, concise, and explicit. You wouldn't just say "Heat the oven and put everything together and bake it." You'd be descriptive and precise. You’d say “Heat the oven to 350 degrees” and “mix together 2 cups of flour, 1 teaspoon of baking soda, and 1⁄4 teaspoon of salt.”
When you're building a WordPress template, aren't you doing the same thing?
Aren't you listing out your ingredients (in this case, a set of variables) and then providing explicit instructions to a webserver to follow? (Hint: you should be)
Coding principles
Syntax and form
You come into coding knowing that syntax is a big deal. You know that, if you do not combine symbols in the correct sequence and with proper form, a computer won’t be able to understand what you want—computers are inflexible like that.
You may not realize that you’ve likely written something else in your life where syntax and form were a big deal.
Anyone who has done legal writing has dealt with specific syntax, jargon, formatting - all sorts of things that are specific to that particular style of writing.
The same is true in academia, especially when it comes to citations.
Another example is screenplays. My brother-in-law is a screenwriter. Nowadays, there are plenty of tools out there like FinalDraft that help us format screenwriting.
Before those screenplay-specific word processors came along, however, there was a HUGE industry based around the proper formatting of screenplays.
If your screenplay wasn’t in Courier font with extremely specific formatting for character names and dialogue and margins and spacing, a movie studio was going to throw it out without even reading it—just like a computer with improperly formatted code.
So, in writing, we’re used to following certain formats. It’s the same thing with coding. It’s just a different form of writing.
Adherence to standards
Mindgrub is a WordPress VIP partner, and WordPress VIP has strict coding standards.
The good news is, just like using spell check with your writing, there are development tools like CodeSniffer to help you stay compliant with best practices or any set of standards you define.
This one is telling us a bunch of things: We’ve got red dots and squiggly lines (in other words: errors).
It’s telling us that we’re processing form data without a valid nonce verification.
It’s telling us that we should use isset() or empty() to check that these exist.
It’s telling us that we can’t just echo them without sanitizing them with one of WordPress’s sanitizing functions.
This is IMPORTANT. If you’re a journalist, think of this as not verifying a quote or fact before printing it. You would never publish without first confirming accuracy. The same is true here. You cannot just blindly echo what a random user has entered (in this case in a URL parameter).
Best practices and standards exist for a reason, and you need to adhere to them.
“DRY”: Don’t repeat yourself
Don’t repeat yourself.
Don’t repeat yourself.
Don’t repeat yourself.
It’s a waste of time.
If you are given an assignment for a 500-word piece, you don’t have time to repeat yourself. You need to get to the point. Fast.
It’s a waste of time in your coding as well, and it’s a waste of file size. You want to apply things to blocks of reusable code whenever you can.
This code still works, right? Sure, but the best coders (and writers) strive for efficiency.
As a coder, you don't want a 200KB javascript file when a 5KB file will suffice (and improve site performance).
“Code is poetry”
If you’ve been to the WordPress.org website anytime in the last decade or so, you’ve probably seen this phase. In fact, it’s in the footer right now.
Code is poetry.
If you look in the Codex at the WordPress philosophy, you will see that of the four tenants they have listed in the philosophy, this is number one.
It’s a whole separate talk to delve into what that really means, but what you should take away from this is this idea of creative writing translating to code.
Think of poetry and think of Emily Dickinson (rather than Walt Whitman-style freeverse) because it’s easy to read.
It’s clean and concise. It’s evocative. It does a lot with as little as possible
That’s what “code is poetry” means. Make your code beautiful and readable. Make it do as much as it can with as little as possible.
Ajax vs. AJAX
Long before AJAX was Asynchronous JavaScript and XML, Ajax was a Greek hero and the subject of a tragic play by Sophocles.
And what do we remember about tragedies from our days in Literature class?
That someone, often the main character, is going to die at the end.
And that's exactly what happens to Ajax in the play.
This is important to remember any time you are dealing with AJAX functions because, at the end of your AJAX function, you are going to invoke WP_die. Every AJAX function you write MUST end with a call to die! Otherwise, they won’t work properly.
Wrapping it up
Writing Principles:
- Punctuation saves lives
- Don’t mix metaphors
- Clear instructions
Coding principles:
- Syntax and form
- Adherence to standards
- DRY: Don’t repeat yourself
- “Code is poetry”
- Ajax vs. AJAX
If you can wrap your mind around the fact that coding is really just another form of writing, with a slightly different language, you can be more comfortable with it.
You can be less afraid to dive in and join the WordPress community, in the same way you would join a writing feedback roundtable if you were a creative writer.
So there we go: we've barely scratched the surface of either writing or coding, but nonetheless we've gone over some analogies and ways to think about coding that should make it more comfortable and more familiar for you if you're coming at it without a computer science degree.
Feeling inspired to start coding like a writer? Drop your thoughts in the comments below!
