|
|
posted: March 31, 2018
tl;dr: Readability (by humans) is the most important attribute of good software...
“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” - Martin Fowler
I’ve long felt that the most important quality of software is readability. Perhaps I developed this bias back in university when I was employed by the Cornell Computer Science department as a grader, which meant that over the course of a semester I had to read and grade hundreds of students’ programs. Yet I have maintained this bias throughout my professional career, and still rate readability as more important than performance, brevity, and even correctness. How can that be?
Performance is certainly important: a program needs to run fast enough to satisfy the intended use cases. Yet optimizing performance can often be a waste of valuable resources, in particular developer time, which is often more expensive than CPU time. If a job is only ever going to be run once, and it currently takes an hour on a standard cloud server that costs $25/month (roughly 3.5 cents per hour), and the developer thinks he/she could get it to run twice as fast by spending ten more hours on it (at a developer cost of $50/hour), then that would be a $500 investment to save 1.75 cents. Not a good return on investment. If we wanted every piece of software to run as fast as possible, then we would write everything in assembler, as every higher-level language (including C) introduces some inefficiencies compared with writing optimized assembly code. So raw performance isn’t the most important software quality.
Brevity is another important software quality, but brevity at the expense of readability is not. The computer’s compiler or interpreter is equally happy to run code with either single character variable names or longer, more descriptive names, but using longer, more descriptive names is a big aid to readability, except for short term, trivial uses of variables.
A Python2 Sudoku solver in 169 bytes...but is it correct?
I even rank readability higher than correctness because I feel that a program cannot be known to be correct unless it is readable. Sure, a highly obfuscated, difficult to read and understand program can be correct and can pass all the test cases written for it, but how can that program be known by others to be correct? What happens when new use cases arise in the future, and the cryptic code has to handle some new data that was perhaps not foreseen by the original author? Can the person running the code at that point in time trust that it is delivering correct output? Readability is needed to have the confidence that the software is actually working correctly.
The benefits of highly readable code are significant and long-lasting:
Readable code minimizes work in the long run. New features and bugs are bound to arise in the future, and a codebase that is readable and understandable by many developers is going to be much easier to enhance in the future. If a codebase is hard to understand, and the original author is not around to enhance it, it might have to be completely rewritten or replaced. I’ve seen plenty of instances where the original author hard a hard time understanding some code he/she wrote months ago, and embarked upon a major refactoring or rewriting. Hard to read code is a major source of technical debt.
Producing readable code helps the career growth of the original author. Few developers want to be stuck working on (i.e. maintaining) the same codebase for years and years. Yet if that code is difficult for other developers to understand, the natural response of the company will be to continue to ask the original author to maintain it ad infinitum, until the original author gets so fed up that he/she quits in a huff. If a developer wants to move onto other new, exciting projects and technologies, it absolutely helps to write readable code that others can maintain.
Producing readable code can lead to long-term satisfaction for the original author and pride in a job well done. The original author should feel happy when other developers are able to step in and inherit a codebase. Some of my proudest accomplishments as a developer are having code of mine that stayed in production for well over a decade, not necessarily in the exact same state, but the same codebase that was enhanced by others long after I left the project and the company.
Some tips to produce readable code:
Craft an elegant, simple solution, as I’ve explained here and here. Avoid advanced, esoteric language and framework features unless needed and unless they help reduce overall complexity. This way other more junior developers can inherit the codebase without needing to have an expert’s knowledge of a particular language or framework. Choose descriptive names for variables, classes, functions, methods, as this helps document and explain the code.
Finally, some comments about comments. I’m not in the camp of “the best written code should be entirely self-documenting, without any comments”. The reason is that the code itself can never fully explain “why” it was written the way that it was. Comments are often necessary to explain why a particular problem was solved a certain way. Some examples where comments can help are: explaining why certain default values were chosen (perhaps to meet the needs of a particular customer or use case); explaining non-intuitive algorithm steps (maybe a list needed to be sorted solely because it helps in restarting a job that has reliability issues due to a flaky network connection); and explaining any subsequent code modifications made due to a bug being found, or a feature request being made, after the code is in production (it can help to have a comment which cites the particular change request). My rule of thumb on comments, which comes from experience, is to realize that when I am writing the original code, I as the author am deep in the rabbit hole and aware of all the issues at the time; but what am I going to fail to remember six months or a year from now, if I have to come back to this code to add a feature or fix a bug? That’s why I like the expression that “comments are Notes to Future Self”.
Write for readability. Your company and your future self will thank you for it.