Writing this Newsletter and Writing Code
Lessons learned from William Zinsser's On Writing Well and my experience writing software
Believe in your own identity and your own opinions. Writing is an act of ego, and you might as well admit it.
- William Zinsser, On Writing Well
William Zinsser’s On Writing Well has been my manual for non-fiction writing. When I decided to start this newsletter, I was well aware I needed guidance on developing my writing skills. While reading the book recently, I noticed many parallels between the crafts of writing nonfiction and writing software. Here’s what stood out:
Simplicity
The simplest solution is often the best solution. The best way to eradicate errors is to define them out of existence. I recommend John Osterhout’s A Philosophy of Software Design for more on this. The book emphasizes simplicity and the reduction of complexity in the design of software interfaces.
Here’s some Javascript code I wrote to process a webhook from an API provider. I wrote this to add chat functionality to the Adapt iOS app.
The code parses out key information from the request, fetches the users that are part of the chat, and then sends a push notification to their phones.
It’s focused on one purpose only.
Reduce Clutter
In On Writing Well, Zinsser writes, “Clutter is the disease of American writing. We are a society strangling in unnecessary words, circular constructions, pompous frills and meaningless jargon. The secret of good writing is to strip every sentence to its cleanest components.”
Remove unnecessary code. If you can’t clearly articulate the purpose of a block of code, get rid of it.Style
Style might mean what patterns you implement in your code, but I think one’s style even extends to your choice of tools. Vim vs. emacs, tabs vs. spaces, etc. There’s no correct answer. Everyone makes their own choice that best suits their needs.
I recommend William Struck’s Elements of Style for tactical advice on writing nonfiction.
My dev tools:
IDE: VSCode, XCode for iOS dev.
Vim (through VSCode extension)
Terminal: Iterm2 + tmux
API testing: Postman
Programming languages: Python for most things, Swift + SwiftUI for iOS dev, Node.js for APIs
A Note on Style:
Does coding style matter less as developers continue to integrate Github Copilot and other AI assistants to assist by automatically generating code? Will everyone’s code converge to the same? This possibility, or maybe even eventuality, doesn’t bother me since software has always been more of a means to an end for me.
Know your Audience
In most software engineering teams, after you’re finished writing your code, you’ll need to raise a pull request. A pull request is a method for having other team members review your code before it is merged into the main branch of the codebase. It’s important to remember while you’re writing your code that eventually someone else will be reviewing and maintaining it.
Words
This is another important principle when writing code that others will read or maintain. Use descriptive nouns for variable names, use verbs for function names, and avoid lengthy file names.
Most of these principles are critical when you’re working with others. For my side projects, I can get away with being a bit loose with these principles for the sake of speed. But I didn’t have this luxury in my previous job when I was writing software as part of a team.
Whether you're writing software or writing a letter, you’re practicing a craft. Hone your use of these core principles and they’ll never fail you.
Leave your comments below if you’re interested in reading more articles like this.
Special thanks to Sravya Varanasi for proofreading drafts of this article.