Keep Your Readers In Mind
When you write an article or a book, you know you have to maintain clarity, simplicity, flow and coherence of your written artifact. You know your creation has to be well written (and even well designed) because people are going to read it. At least you hope they will. You know you are writing for your readers, so you have to keep them in mind throughout the writing activity.
“Is this the software quality blog?” you might be wondering. Well, it is. Writing code is much like writing a piece in English (or any other spoken language).
Telling the compiler what to do is relatively easy, but that’s not what writing code is about. Writing code is about communicating with another developer. A developer who might sit in the next room or a developer you might never meet. The product you write today is most likely to live and evolve for several years. The code you write might be part of the product long after you will be promoted (or decide to become a consultant). The developer that will take over the product must be able to understand the code you write. She should be able to read it and make sense of it in the most natural way possible. She should be able to fluently read it without having to find you to explain it to her. Why? Because this will save a lot of money to your company, and make the product you write today more profitable.
The fact is the source code is not written for the compiler. It is written for human beings. This is why programming languages are being constantly refined and reinvented, although the machine code generated by compilers stays pretty much the same. So, if you write code for a human being to read, you must keep your reader in mind when writing it.
Unlike writing in English, when writing in Java, C++, C#, Perl, or any other language, you are not always thinking about your successor. Many developers think of their code as their own private possession – some sort of notes taken just to create the real product. But in the real world, code is always being read by additional people as the product evolves.
So, what you have to do in order to write human-friendly code is keep it simple, fluent and use constructs which resemble natural language as much as possible. How will you know that your code is well written? Well, just like when writing a book, a professional review is not a bad idea. If your reviewer verifies not only the correctness of the code, but also its clarity, you can be sure that the developer that will have to work with the code a year from now has a good chance to understand what you meant when you wrote it.
Related Article: Code Usability
