Code. Coding. Everybody is talking about it — even the President of the United States. Except me — I literally want nothing to do with writing code for the rest of my life since I’m sick and tired of it. Unfortunately I am not financially independent enough to outright completely walk away just yet, but I will indeed endeavor to never again write even a single line of code, even though reading of code will be a significant activity for me in the coming years. It is that need to continue reading the code of others that motivates this article.
I was planning to write a short article on code quality but as I started writing the project became a lot larger and more complex than I originally imagined. This article is a preamble for a collection of articles, all related to aspects of code quality. So, on with my introductory, prefatory comments.
Background and Motivation
I myself am no longer a practicing software developer (i.e., coding on a regular basis), but do still read a fair amount of code, usually in GitHub these days. Mostly I am just plain tired of writing code, having been there and done that way too many times. In truth, I’m more of an idea guy, a planner, more interested in concepts and understanding than execution and implementation. Sure, I want to see ideas implemented and wish to have an advisory role in execution and implementation, but I get no personal satisfaction from doing the execution or implementation myself. I do like to ponder and work through feasibility issues, but at more of the design and architecture level than the coding level. On the flip side, I am very interested in bit-level encoding and efficiency of algorithms and data structures, but again not the writing act of writing the code itself.
One thing I do sense lurking in the background is the extreme gap between solid but abstract ideas and high quality and efficient implementations of those ideas. It just seems to me that there are far too many obstacles between the two. I’m sure that much better programming languages could help to bridge the abyss, but for now we (okay, the coders) have to work with what we have in the here and now. But the presence of that abyss means that I myself have a very clear preference for the conceptual side of the fence even as I am rather dependent on the implementation side of the fence.
Code as Specification
The reality of so much software today is that the documentation and specifications are so… weak (trying to find a semi-polite term!)… that you almost (okay, usually) have to look at the source code to understand what the rules really are, and then… much of the time the code leaves you scratching your head or at least taking way too much of your time and progress towards comprehension is way too slow. Sure, you can just run the software and see how it behaves, but I’m a specification guy at heart, so I prefer to consult the ultimate specification, the code itself.
Coding Bumps into Reality
I’m also interested in how long it takes to complete software projects — or at least evolve them to their next stage, how many bugs they have, how short they fall of (my) expectations, and how inflexible and difficult to maintain so much of today’s software really is, even for leading open source projects.
Who Really Cares?
I am rather disturbed by the apparent extreme disinterest in code quality on the part of management. The more common refrain is “When will it be done?” rather than “How much higher quality can we make it?” I write these words the day after the 30th anniversary of the Space Shuttle Challenger disaster, one of the more prominent footnotes in the history of technology when it comes to failures of management to comprehend quality and how it relates to safety. Meanwhile, every day, managers turn too blind an eye to code quality. “Wow, you would not believe how much higher the quality of our code is due to the tireless, dedicated, and persistent efforts of our management!” said no one ever. Okay, sure, sometimes individual managers actually do push for quality, but even then more at the software or product level — measured in features and bugs — rather than in the source code itself.
What are Our Priorities?
We are awash in a sea of low-quality code that is in that sorry state either because nobody notices or really cares. Okay, maybe somebody does care, at least sometimes, but as with Challenger, not enough to do anything really significant about it. The stumbling block for a lot of otherwise professional developers has always been that spending anything considered extra time on code quality has almost always been treated in a very negative manner by management. Sure, occasionally, managers may schedule a little time for code cleanup or rewriting a module that is too bug-prone, but a little modest cleanup of code per se falls far short of first-class code quality across the board.
In short, it is more than a bit more than difficult for me to have any enthusiasm for ever again doing any coding myself. Besides, we should all focus on what we can be passionate about. I’ll leave coding to those who are indeed passionate about coding. Me, I’m a lot more passionate about quality and exploring phenomena, such as this gaping abyss between code and quality.
I can probably safely say that low code quality was the straw that broke the camel’s back for me. That’s not quite true, since there was a lot more to it, but I certainly wouldn’t be embarking on this significant effort focused on code quality if there wasn’t at least a little truth to it.
Doing it for the Kids
Even in the mainstream media and politics there are efforts afoot to drag a lot more people into coding, so it seems advantageous to try to help people better understand what code quality is really all about and how to improve it before a lot more people start out repeating so many of the errors of the past (and present.)
My apologies in advance to all of those dedicated individuals who do indeed strive to produce high quality code. Exactly why their best intentions are not always met will be fodder for discussion. I am not trying to say that there is no high quality code anywhere, but simply that the vast bulk of source code is not even close to what I personally would characterize as high quality. Granted, others may have their own standards.
Code Quality vs. Software and Product Quality
One of the complexities of this project was that I quickly realized that there are plenty of aspects of software quality that are not directly tied to code quality per se. There is documentation, packaging, training, and marketing that are definitely related to the quality of the overall product experience, but not directly tied to either code quality or even software quality. I finally realized that there is a whole hierarchy of levels of quality that are beyond the scope of the raw source code itself.
Levels of Software Quality
Granted, all of these other levels of quality really are beyond the scope of my immediate interest in code quality, but I actually am quite interested in all of these levels, and so many of them have a way of indirectly influencing code quality anyway. I won’t delve very deeply into them before I focus more on the quality of the code itself, but I do find it useful to see the full context into which code quality fits.
I’ll use the term software fairly generally as any package, product, or service that has code as its fundamental base. Product and service are slightly more descriptive terms, but that degree of nuance will be lost on most people until they start diving deeper into this material.
From the top down, here are the quality levels or tiers that I have identified:
- Social satisfaction — Impact on real people whether or not they even directly use the software product or service.
- Customer satisfaction — The product may work as intended by the developers, but do the actual users find that it satisfies their requirements, needs, and expectations?
- Enterprise satisfaction, success, and effectiveness — Again, the product may function as intended by the developers, but does executive management see that it helps them achieve their top and bottom lines and other enterprise-level goals — does it lift the overall organization or drag it down?
- Product quality — Beyond the raw software itself, how does the packaged product behave and perform, including documentation and training?
- Service quality — For software that is destined to be an online service, such as a web site or cloud-based application, there are many aspects of quality that may be somewhat different than for packaged software or downloaded applications, including usability and user experience, response time, availability, privacy, and security.
- Team quality — How well are the developers and rest of the product team organized and work together as a team rather than as individual developers?
- Process quality — How effectively and efficiently does the team proceed through all the stages of development, including methodologies.
- Tool quality — How effectively and efficiently do tools help team members organize and communicate their thoughts and work products and otherwise automate tasks and assist team members in performing their tasks?
- Technical Leadership Quality — How do the key technical decisions made by the senior architects and technical management impact all quality levels, especially product, team, process, tool, and overall software (not to mention code itself)?
- Management Quality — How do management goals, planning, budgets, day to day supervision (and micro-management), motivation, staffing and team composition, personnel management, reviews, etc. impact all quality levels?
- Software quality — Beyond the source code itself, such as the requirements, functional specification, architecture, subsystem-level design, external interfaces, data and configuration files, file formats and data models, source control, build process, build artifacts, etc.
- Code quality — The programming language artifacts themselves, the source code files, including module and file composition, declarations, naming conventions, sequencing of operations, individual statements, expressions, data structures, comments, and use of white space.
Again, the goal here is not to fully cover each of those quality levels, but to simply paint a broad picture of the contextual framework in which code quality is situated.
Code Quality Factors
Okay, I realize that all of this preamble stuff is an annoyance, but the main reason for it is to get all of this peripheral but related stuff out of the way, so that when we speak of code quality people aren’t getting distracted about software, product, process, and team quality, for example.
If you really are waiting for discussion of specific factors for code quality, you will have to wait for the successor documents since this document really is only the preamble. Sorry.
The incredible saga of HealthCare.gov illustrates so many of those levels of quality, especially the higher levels of social and customer satisfaction and management. Although, to be honest, from all the public writing I’ve seen I can’t sense that the code itself (as opposed to architecture, management, and deployment) drove the fiasco. Yes, architecture, deployment, and hardware provisioning matter greatly for Internet services, but are essentially completely independent of the source code itself.
In short, HealthCare.gov is great fodder for a discourse into software quality and service quality, but won’t shed a lot of light on code quality per se. For my immediate purposes I am focusing on the end result itself, the actual source code, independent of exactly what confluence of forces led to the code being the way it is. Yes, I’ll at least enumerate all of those factors and forces when I first discuss software quality, but my goal is to quickly get all of that preliminary and contextual stuff out of the way so that I can focus primarily on the quality of the actual source code itself.
Shortly I will delve a bit into each of those upper tiers of quality to some degree in an article tentatively entitled Software Quality. At some more distant future date I may delve more deeply into each tier by itself.
Once I have finally gotten all of those preliminaries out of the way I will finally directly address code quality itself.
My preliminary intentions are to produce multiple articles on code quality itself:
- Code Quality — The Big Picture. A relatively brief summary of the major categories of factors of code quality
- Code Quality — A Taxonomy. Enumerate all the many aspects of code quality. Heavy on bullet points and light on narrative. It is not my intention to teach people people all the details about coding, but to simply lay out a conceptual framework for the many key elements of code quality.
- Code Quality — Discussion. Walk through my thinking about a subset of some of the more significant or knotty aspects of code quality from the taxonomy, including obstacles to success and possible solutions wherever possible. This may end up being a succession of documents.
- Code Quality — Epilogue. Looking back on the project, to close the loop on what was started. Address feedback. Summarize any needs for further research.
None of those titles is cast in stone yet and the precise order of production is not guaranteed either.
As I get even deeper into this project I may decide that I need to have more or different branches on this tree of articles.
There may be additional articles on narrower or broader perspectives on code quality as well.
Rather than hold off while I pursue perfection, my intention is to publish one or more drafts for each article as quickly as possible before I claim that I have satisfied the intentions expressed in this preamble. In some cases these drafts may be mere outlines or bullet points.
As an alternative to or in addition to drafts I may just go ahead and publish my raw notes, simple bullet lists with no supporting narrative. This would permit an earlier stage of feedback and also assure that I have more of the overall material at least minimally covered at an earlier stage.
I might in fact opt to publish my raw notes ASAP and then hold off on upgrading them to drafts and final copy until I have gotten at least some preliminary feedback and at least a minimum level of encouragement to continue pursuing this project.
Bullet Points vs. Narrative and Storytelling
I show no potential for being a budding novelist. I’m really not into so-called storytelling and extended rhetorical narrative. I’m more of a to-the-point kind of guy. In fact, lists of bullet points are my preferred writing style. Or lots of short paragraphs with pithy headings like this one.
Examples and Tutorials?
My focus is more on the abstract concepts and conceptualizing a framework for discussion rather than attempting to teach people Code Quality 101. I’ll leave it to others to pursue detailed examples and tutorials on code quality.
Surprisingly (not), I am not the first person to write about code quality, software quality, or product quality. I’m sure someone could write an entire book summarizing the literature relating to software quality alone, but I’ll refrain from doing so. Mostly I am writing from personal experience and personal observations and my own reflections, although I can certainly attest to having learned a thing or two from the experiences of others.
My personal experience is that I receive very little useful feedback on the things that matter the most. Sure, feedback is always welcome, but I won’t be holding my breath waiting for feedback. My sincere apologies if I don’t focus an excess of energy on addressing feedback.
As I alluded to earlier, I am not asserting that I invented the wheel called code quality or software quality. My writings will primarily be my own personal analyses and formulations of concepts as I see them though my own eyes, but there certainly is a very long list of people whose own work has influenced me over the decades of my career as a software developer. I’m not going to list individual colleagues and bosses, but I will list a few of the more public figures whose writings and works led me to this moment and decision to pursue this small project on code quality.
- Edsger Dijkstra, whose infamous ACM letter, “Go To Statement Considered Harmful” got a lot of people thinking about a lot of stuff, including code quality.
- NATO Software Engineering Conferences, 1968 and 1969. Super-impressive stuff by stellar computing giants of the time. Source of the infamous quote that “We build systems like the Wright brothers built airplanes — build the whole thing, push it off the cliff, let it crash, and start over again.” Cute, but a little off base since the Wright brothers actually did primitive wind-tunnel testing first to prove the concept and then iterated over sand dunes, not deadly rocks. That said, plenty of lessons learned here.
- Bell Labs adjunct professors for my computer science grad courses at Stevens Institute of Technology, including Alfred Aho on language theory and compilers and parsing and Brian Kernighan on software tools.
- The computer center at Stevens Institute of Technology where I worked as as a programmer while a student. I got to work with a bunch of really smart guys and had full access to the source code for the PDP-10 TOPS-10 operating system, compilers, and utilities/tools. I think I can safely say that I saw better comments and module and data structures in assembly language code back then than I see in code with high-level languages today.
- Donald Knuth of “The Art of Computer Programming” fame.
- Joel Spolsky, whose “Joel on Software” blog and book(s) have done a very decent job of focusing people on a lot of software quality and development process issues in the modern day, including many factors that are outside of the source code itself but influence the resulting code.
- Paul Ford, who wrote the famous and popular “What is Code?” article for Bloomberg Businessweek. He literally is the initial inspiration for me embarking on this writing project as I was pondering how to get his attention to try to get some contract work with his new agency, Postlight.
Quite a few computing projects and groups and companies over the decades have also influenced my own thinking. Just a few:
- MIT AI Lab
- MIT Multics project
- Digital Equipment Corp. — the PDP-10 culture
- Bell Labs Unix and related projects
- Xerox PARC Alto
- MIT Lisp Machine
- BBN — amazing computing projects in the 1960s and 1970s
- Carnegie-Mellon University (CMU) computing projects
- Stanford University computing projects
- Tim Berners-Lee — web browsing, HTTP services, and Semantic Web
- Google and predecessors — web search engines, which are now more than half of my conscious “brain”
- Apache Software Foundation — open source software
I also need to acknowledge Southern Regional High School in Manahawkin, NJ for giving me unlimited computing access back in the days when computers cost real money. I actually enjoyed coding back then. Ah, the so-called good old days.
My apologies for not listing so many of the companies, organizations, projects, and individuals who have had such a profound influence on my own professional and intellectual development over the past four decades.
All of the above are hereby indemnified for any ideas that I express that do not reflect positively on them.
As soon as I hit Publish, I’ll focus on the next article in this series. So many possible choices. I do hope I’ll get some feedback to influence that decision.