Coding with humans in mind
We all agree. Documenting code is a waste of time and a considerable cost. It is much better to refer directly to the code if you want to understand how an program works internally.
Of course the intention is good, but what if we run into a snippet of code like this?
const f = (st, p) => p.filter((i) =>
i.title?i.title.includes(st):false||
i.keywords?i.keywords.includes(st):false);The JavaScript code is perfectly working. It does its job properly. But exactly what is its job?
Considering the code as documentation may be a nice idea, but it remains just an idea if we do not strive to change mindset when we write our code.
As Martin Fowler says:
“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”
The problem is that when the developer writes his code, he usually thinks about how the computer will execute it to solve a given problem. He does not care about humans who will read the code (including himself after some time).
But if we want our code is readable to a human being, we must think of him in the first place. This is the basic rule of the writer: when we write a technical document, a blog post, a magazine article, an essay at school, we have to think about the reader and put ourselves in his shoes to see if what we have written can be understood.
It is not easy, because the writer must try to imagine if what is clear for him it is equally clear for a generic reader, and readers are not all alike. Obviously the writer and the reader must have a common knowledge base to be able to communicate, but the writer cannot assume that the reader understands on the fly what he wrote.
One way to get as close as possible to an acceptable outcome is to imagine one of your colleagues as a reader of your code or, even better, ask directly to him if the code is understandable.
In short, if you want your code acts as documentation of itself, write it thinking of a human being who will read it rather than of the machine that will execute it. All in all, the high-level programming languages used by the vast majority of developers have been created to make life easier to humans rather than to machines. Especially since the machines do not use the code written by us, but the low-level one generated from it.
That being said, we can rewrite the code above giving it a more human appearance, with one more chance to be documentation of itself:
function getFilteredPages(searchText, pages) {
let isInTitle = (item) => item.title?
item.title.includes(searchText)
:false;
let isInTagKeywords = (item) => item.keywords?
item.keywords.includes(searchText)
:false; return pages.filter(item => isInTitle(item) ||
isInTagKeywords(item));
}
Even if the code is a bit more verbose, it’s definitely easier to guess at its purpose without the reader has to identify himself in the machine that will execute it.
