Communicate to Code
Writing prose can improve your programs and make you a more valuable asset.
Programming rests firmly on the foundation of math and logic. Writing is bound by an inconsistent and evolving set of rules. The electronic mind of the machine is coldly unforgiving when executing a buggy program, while essays riddled with problems are published constantly without any major issues.
Superficially, these two activities don’t seem all that related; however, I think that programming and writing actually have a lot in common, and that by practicing one you will improve at the other and more.
Your code has two audiences
Programming is fundamentally an exercise in communication. When writing a program, you are communicating with two audiences—the first one just happens to be the computer. Until our robot overlords finally get their emotion chips installed, communicating effectively with this audience just means that your code has to run. After all, what good would a program be if it didn’t even work? This is the minimum viable bar for success.
For those with higher aspirations, keep in mind your second audience: the people reading your code. To consider yourself successful here, these people must be able to make sense of it all and understand what the heck is going on. As Structure and Interpretation of Computer Programs put it:
“…programs must be written for people to read, and only incidentally for machines to execute.”
Not important, you say? Even though your team gets stuck with all of the shortcuts and spaghetti code you never took the time to refactor or document, you’ll be so far off the grid by the time they bump into it that they won’t be able to track you down even if they wanted to, right?
Well, tell me if this scenario rings any bells: you’ve been working on a project for a while now and come across a truly grotesque pile of copypasta. As you reach for the git blame, you grow excited with anticipation of raining down righteous justice on the sad fool who thought it was committable in the first place. *bleep bleep bloop* (or whatever computers do when they are thinking) and git blame slaps you across the face with your own name. That’s right, past-you just handed future-you the short end of the stick. It’s a humbling experience.
If I keep in mind that the person who ends up maintaining my code is me, I usually end up treating it with a little more discipline and am able to avoid this scenario most of the time.
When wrapping up a commit, I give it a quick once-over, usually as I stage my changes using git add -p. Here, I make sure that things are named clearly (one of the hardest problems in computer science), the functions are well-ordered, and that the parts of the program are properly broken up into the right pieces so they can be understandable to the people reading my code. In programming, we have functions, modules, and files to do this work while in writing, we have sentences, paragraphs, and headings.
Write to improve your code
I use similar proofreading skills before publishing an essay or blog post, except instead of naming variables I think about word choice. Instead of ordering functions I think about how it flows. And instead of abstracting complexity I start new posts. It’s all the same stuff under the hood, and I think it goes a long way toward making it a successful piece of work. Cultivating your written communication skills offers similar benefits to the realm of programming.
For instance, after practicing your writing, you might find that people can more easily understand your code comments. Obviously, your commit messages and documentation (you are writing documentation, right?) will improve. Better writing skills will even help you become a code review hero, which will reverberate positively across your codebase into the future.
However, I think that writing will help you improve your code in additional, less obvious ways.
Rubber ducking’s great uncle
I sometimes run into a challenging problem that I don’t quickly see the solution to. When in this situation, I often find that rubber ducking—talking someone or some inanimate object through the problem at hand—can help me come to a solution. However, this is not a silver bullet.
If simply chatting up my stress ball doesn’t work, I’ve found that writing about it might help—it’s like writing is rubber ducking’s great uncle. Writing helps me counteract the curse of knowledge, which is related to shoshin (初心), or “beginner’s mind”:
It refers to having an attitude of openness, eagerness, and lack of preconceptions when studying a subject, even when studying at an advanced level, just as a beginner in that subject would.
When I write, I focus in on my topic and approach it from different angles than I otherwise would have. I examine my preconceptions and explore additional avenues. In this way, writing helps me get closer to shoshin.
Just like @CarrieKScully, I can’t count how many times I’ve gone over to a project’s issue tracker or Stack Overflow to ask a question, and by the time I’m done writing it up I have figured out the answer.
Kaizen and the art of learning deeply
At Brigade, we value learning things deeply and continually improving, which I think of as kaizen (改善). To help make sure that our engineers are always growing, some have been encouraged to practice “study hall” where for an hour a day you can choose to learn about something not necessarily directly related to your current tasks. I think of writing as an important learning technique, and I’ve found that it is a great way to practice both of these things during my study hall time.
For instance, if there is some code that I haven’t quite wrapped my mind around, it can be valuable to refactor it for understanding even if I throw away my changes. Likewise, writing about code is a great way to learn more about it because it acts as a vehicle for deep-diving, even if I end up just discarding what I wrote.
Writing also acts as a metacognitive learning strategy that promotes deeper reflection. This is why I think it works particularly well for solidifying my ideas around why I do things the way I do them. By the end of a writing session, I am usually able to more clearly see and express relatively abstract portions of my process. The Writing Across the Curriculum movement is evidence that others find this to be similarly beneficial.
Our brains, language, and programming
It makes sense that programming and language are related. And science might actually back this up: a recent study looking at programming and the brain has been published. Although it was inconclusive, fMRI scans hint at a link between programming and the language centers of our brains:
“There is no clear evidence that learning a programming language is like learning a foreign language, but our results show that there are clearly similarities in brain activations that show that the hypothesis is plausible.”
It might be time to start thinking of writing as cross-training for your brain.
What they never told you in school
If you earned a degree in computer science, you probably focused on things like algorithms and compilers. While these fundamentals are important for getting the job done, in my career I’ve found that communicating effectively with your team is one of the most important things you can do as a software engineer.
In any branch of science, communication is the implicit goal. The researcher studies and then reports back, communicating in a way that allows for a repeat of the experiment in order to verify results. The problem with computer science is that the first audience is the computer itself, and it is able to give instant feedback, so oftentimes the fellow scientists are left out of the loop.
Communicating effectively with your team is one of the most important things you can do as a software engineer.
I believe that how you work with your team will determine your success. Whether this collaboration manifests as clear emails or sharing a great tip about that thing you just learned, strong writing skills make you a more valuable member of any organization.
For instance, you probably know how to do some things particularly well. Writing down and sharing that knowledge will help you level-up your team without repeating yourself. If you are new to the team, this is a great way to build your reputation, and when someone new joins, getting them up to speed can be as simple as sending them a reading list. Each time I pushed one of these posts, it felt like I DRYed up my interpersonal communication stack a little, leaving more time for me to build things and giving my colleagues a document to reference.
If you publish your writing, you have access to even more benefits. For example, it can be a valuable recruiting tool. People will read about all of the great things you are doing and want to join you. On the flip side, publishing builds your online presence. This helps others discover your great talents when trying to be recruited or give you the edge when landing that job. And, if you are a freelancer, writing can even help your business.
Writing and coding are linked, with the coder and the code as partners in communication. It can sharpen the way you think—and by cultivating your writing skills, you improve both yourself and your code. Practically speaking, writing is an indispensable troubleshooting tool, and communicating about your code through prose is essential for all who maintain a code base. As your team scales, it can save you time and energy by bringing colleagues up to speed quickly. Finally, your writing will show your strengths as an employee and can help you earn a reputation for yourself and your company. So what are you waiting for?
