Title: The Art of Readable Code: Simple and Practical Techniques for Writing Better Code
Authors: Dustin Boswell & Trevor Foucher
Contents
- Code Should Be Easy to Understand
- Packing Information into Names
- Names that Can’t be Misconstrued
- Aesthetics
- Knowing What to Comment
- Making Comments Precise and Compact
- Making Control Flow Easy to Read
- Breaking Down Giant Expressions
- Variables and Readability
- Extracting Unrelated Subproblems
- One Task at a Time
- Turning Thoughts into Code
- Writing Less Code
- Testing and Readability
- Designing and Implementing a “Minute/Hour Counter”
Source: The Art of Readable Code
My Story
When I first arrived at Stanford a few years back, I was shocked by the disarray in which project files were being “organized”: no discernible structure, no standardization, no version control, etc. It was sheer confusion as I waddled through the files trying to figure out what was what. For example:
- Is “analysis teacher turnover v3.do” or “analysis teacher turnover final.do” (same date-stamp) the latest version of the program file?
- Does “analysis teacher turnover.do” have to be run before or after “analysis student turnover.do” … or does order not matter?
It was not only how files were named but the content of the files i.e., the code. It was as if I was reading someone’s diary and getting a gist of the underlying story swathed in inside jokes, unique lingo, and subtle inflections. The problem is code shared and collaborated across a team cannot be a personal journal of more or less rambling thoughts. If a graduate student or staff researcher on our team had left, his/her replacement would have little idea of how to replicate or update the code — or at least would have to spend an inordinate amount of time playing Sherlock Holmes. I wouldn’t even be surprised if the author wasn’t able to figure out the code without jolts of memory defibrillation.
Hence, as soon as I settled in, I wrote a manual of best practices for planning, organizing, and documenting code. Adopted by 30+ professors, graduate students, and staff, I called my manual the “POD”, drawing inspiration from J. Scott Long’s “The Workflow of Data Analysis Using Stata“. I wasn’t an expert on the topic but I had enough experience to share my know-how to lead an otherwise blind team towards adopting basic efficiencies (e.g., readability, consistency, etc) for reproducible research.
Some of the best practices in my “POD” manual echoed those in “The Art of Readable Code” including:
- Packing information into your variable, function, and class names (8)
- Choose specific words
- Avoid generic names (or know when to use them)
- Use concrete names instead of abstract names
- Attach extra information to a name, by using a suffix or prefix
- Decide how long a name should be
- Use name formatting to pack extra information
- Aesthetics (34)
- Use consistent layout, with patterns the reader can get used to
- Make similar code look similar
- Group related lines of code into blocks
The Art of Readable Code
Boswell & Foucher lay out a lot of useful tips and step-by-step examples demonstrating the “art of readable code”. While the purpose of the book is not to teach the art of architecture or design patterns, the essential basics are covered: naming variables, including comments, formatting code (e.g., column alignment, blocks, logic order, etc), simplifying loops, etc. Sure, many of these things may seem intuitive or could have been figured out on-the-job but if not, this is a great place to start. And, for those who have already mastered these practices, reiteration of the “why?” and “how?” is always a helpful reminder of what can be dismissed as common-sense or second nature.
The key idea behind the teachings is:
“The Fundamental Theorem of Readability: Code should be written to minimize the time it would take for someone else to understand it.” (3)
What I love about this book is its plethora of examples illustrating the multiple ways in which you can implement the Fundamental Theorem of Readability. Examples are provided in C++, Java, JavaScript, and Python. But fear not if you are a newbie to programming or an expert in some other language, say, Stata! You do not need to be proficient in any of these languages to understand the concepts being illustrated: the beautiful code “art” vs. the uglier stuff. And, if you do get lost or intimidated, each chapter is wrapped up with a summary that bullets the key principles and techniques so you will always have the takeaways in plain English.
: code me stat : 