This style guide builds on my R for Data Science style guide as set out in the 1990s and updated regularly since, and as published in my Essentials book and in the online Data Science Desktop Survival Guide. My mantra is to write my code for other humans to read and to enjoy reading.
It is an art to be able to communicate to others through our programs. As software engineers we use language both to communicate to others and to communicate to the computer. Irrespective of whether we use a programming language or a natural language, our focus needs to be on communication and an understanding of who we are communicating to. Indeed it is this last point that is often misunderstood. As programmers we spend most of our time reading other peoples programs and increasingly, people not trained in software engineering are reading other people’s programs. Programming languages become the means of communicating between people.
We can be as creative and differently expressive and personal in using programming languages as we are in using natural languages. Indeed, we can sometimes identify the authors of narratives written in a particular programming language, just as we might identify a Shakespearean play from a Noël Coward play.
Thus when we communicate with each other using programming languages, we must keep in mind that it truly is a mechanism for communicating to other people.
Of course our programs must be executable by computers but computers generally care little about our programs except that they be syntactically correct. So our focus should be on engaging others to read and understand the narratives we present through our programs. A badly written and presented program is not a pleasure to read. And it’s not a pleasant experience for the computer either, in the sense that where care is not taken, our narratives will more like have bugs.
Please, aim to write programs that clearly and effectively communicate the story of our code to others, no matter how short or long that program is. Think of the other person. Have empathy for those who need to read what you write.
In the following sections we present simple stylistic guidelines for programming in Dart/Flutter that support and encourage the transparency of our programs. Our programming style aims to ensure consistency and ease our understanding whilst of course also encouraging correct programs for execution by computer. Over time develop your own stylistic nuances and idiosyncrasies, and share them.
Note that I don’t agree with everything in the following guides. One area I seem to be at odds with the world is the avoidance of Egyptian Brackets. The style was introduced in Kerninghan and Ritchie’s bible for all of us early C programmers. It was back in the day of printing code on paper and tiny screens. It was important not to waste space. Get over it for real. Space is good today and our priority is toward our fellow human readers. Aligning the start and end curlies improves readability. Unfortunately Egyptian brackets live on in flutter and the opinionated dart_style package encapsulates the wrong opinion, in my opinion.
Your donation will support ongoing availability and give you access to the PDF version of this book. Desktop Survival Guides include Data Science, GNU/Linux, and MLHub. Books available on Amazon include Data Mining with Rattle and Essentials of Data Science. Popular open source software includes rattle, wajig, and mlhub. Hosted by Togaware, a pioneer of free and open source software since 1984. Copyright © 1995-2022 Graham.Williams@togaware.com Creative Commons Attribution-ShareAlike 4.0