About a year ago, I read a fantastic book On Writing Well by William Zinsser. I spend quite a bit of time using the written word to convey ideas and authoring code to create software. There are many parallels, perhaps the most important of which was Zinsser’s proclamation:
Writing is hard work. A clear sentence is no accident.
– William Zinsser
The same can be said about code.
Writing code is hard work. Clear code is no accident.
Of course, the audience of a book and the audience of code are somewhat different. A book is meant for mass consumption. Code is often only ever read by a handful of individuals and a computer to carry out the desired actions. Nonetheless, much time is spent by a few individuals, reading, re-reading and changing code. Clarity, understanding, meaning, concision and many other characteristics are just as important when authoring code.
That said, writing clear code isn’t an end in itself, and one could get carried away. But it deserves consideration that there is a balance to investing in writing clear code versus getting the computer to do what you need it to do. Many people see code as a means to pass instructions to a computer, and don’t think enough about others and even their future self needing to re-comprehend and perhaps change the code in the future.
I’m not a fan of gold plating, so I’m hesitant to suggest for future purposes to always make code clear, because who knows if future purposes will pan out. In other words, for any one peice of code, we may throw it away before we ever need to re-read or change it. However, if one invests in writing clear code as a habit, then there’s no tradeoff to be made. Not only will the computer know what to do, others will understand with minimal overhead, what the software does.
This habit is valuable because most code ends up being re-read, often months and years after it was created, and change is rather common too. It’s not like the majority of software is written once and then the code is swept under a rug never to be seen again.
There are a host of benefits to writing code well, for example:
- Helps clearly convey what the code does.
- Reduces the translation necessary to understand and discuss the code.
- Reduces erroneous assumptions about what the code does. Assumptions that can lead to mistakes when changing code.
- Reduces mistakes from a lack of clarity.
- Makes it easier to change the code.
- Makes it easier to understand past decisions.
A course on writing code well.
Because writing code well can be extremely valuable, I’ve created a course that dives into detailed examples of the myriad of aspects that come into play. I chose video as the channel to discuss and manipulate examples. To consider tradeoffs and to convey advantages and disadvantages of various techniques.
I’m starting with JavaScript as a language because it’s rather universal and the conversation can carry over to many related languages. Eventually, I will create similar discussions for other languages and platforms too. At this point I have three sections complete and will continue to add more. The first three sections relate to meaningful naming, the structure of code and the role comments play.
At the end of each section, I put together a hands on example that challenges you to apply the techniques discussed. This is a great way to solidify learning. After you’ve taken a swing at manipulating the hands on example, you can watch my commentary on the changes I chose to make. I’m extremely excited to share this course and open up what goes on in my mind when I approach writing code. The course is a distillation of making tacit knowledge explicit to help you get in the habit of writing code well.
You can access the course here: On writing JavaScrit well. Both the promo video and the first section are a free introduction to the course.