Be a great reader in order to be a great writer
The most over-looked skill for a software engineer is reading.
Every developers favorite project is the “next” one, where there is no code yet and everything is a blank editor. There’s freedom and adventure in writing code to solve a problem and not being constrained by previous frameworks or dependencies. In order to write great code however, you must first have read a lot of great code, and really bad code.
It’s rare that you get the opportunities in your career to start from scratch. Most often we are thrust into existing systems and code that has been likely edited dozens if not hundreds of times. So the next time you have the chance to start from scratch, remember that the best way to write code is to read code and absorb the lessons of the past.
Clarity by example
The goal of any bit of code is to perform some function to achieve an outcome. If you are thinking in just those literal terms, it could be argued that it doesn’t matter how legible the code is. You could also subscribe to the idea that code is to be read by computers and not by humans. But we simply don’t live in that world. Most if not all code today is read by humans in order to express intention. It’s only circumstantial that it all gets compiled down into code that is read by computers.
Writing code that is clear and expresses its intent is not as easy as it sounds. In fact depending on the language, you could find yourself writing dozens of lines of code that seem disconnected to each other. The comprehension of some code is really up to a shared understanding of everyone involved in the writing of the code. And inevitably this relies on the code being written in a manner to be the most comprehensible, such that a reader can take away its intention.
The way in which most people become good at writing really understandable code is mostly by reading lots and lots of other code and using it as reference. It’s obvious what to avoid when you read code and not understand how it works. But the importance of clarity is not always absorbed when you read code that makes sense. Sometimes you just walk past that fact because that’s the point: you should be able to read the code and make sense of it. Doing that successfully isn’t always appreciated, rather it’s only respected when you read poorly written code.
Context is everything
One quality of code clarity is that it provides the context in which the code is running. This is extremely complicated because there are so many ways in which context can be lost, abstracted away, or simply ignored in code. Naming variables is the first and most often poorly done aspect of code context. A bad variable name could completely remove the important context for the code and how it’s executed in a larger system.
More than variable names, the flow of code is important and this can be complicated in multiple ways. There is the literal logic flow, that might be nested try/catch statements or a wall of if/else conditions that are simply too many to mentally model. There is also the flow of operations in code that can be abstracted away and removing all the context for when or why the code you are writing is being executed.
There is always a context in which the code is intended to be used, and where it should not be used and this is another easily missed quality of code. We should always try to make clear the purpose of the code, and easily represent what it’s most suited for.
Reading is the best path to great code
It’s not an intuitive idea. One could easily say that the best way to become a great code writer is to write more code. Practice makes perfect right? This is a trap. Reading lots and lots of code is the very best way to improve your writing skills. It’s the only way to force empathy into your code. All of us have read really poorly written code, but instead of taking it as a lesson or example of what not to do, we usually admonish the previous authors. Rarely do we say to ourselves “this is a good example of how to make code confusing”.
And thereby we don’t take the opportunity to give poorly written code its ultimate value: a lesson. It is the best lesson we can learn on how to write good code. So the next time you’re staring at a blank editor, take a moment to go read code. It’s the best first step to writing great code.
More reading on this topic:
