Should software engineers write code for people to read, rather than for a computer to read?

Question

I have heard of:

“Programs must be written for people to read, and only incidentally for machines to execute.”

― Harold Abelson, Structure and Interpretation of Computer Programs

and Donald Knuth said that too:

https://www.youtube.com/watch?v=CDokMxVtB3k&feature=youtu.be&t=1768

but very often at work, I just read programs that have lines of lines of them, without saying what it tries to do. For example, I can be reading 17 lines of code, and wonder what the programmer wanted to do, and after a couple of minutes, only to found out it was just to filter out some data into 2 sets and get the intersection. The same thing could be done in 2 or 3 lines. Or if there was a comment at the beginning of the 17, 18 lines

# put data into 2 sets and get the intersection

then I wouldn't have to follow line by line and find out what it was trying to do.

Some people say: "you should be able to understand the code 'as is'". While that is true, why waste 5 minutes again and again here and there, and for other people as well, when 2, 3 lines of code, or 1 line of comment of what the intention was could let anybody know in a few seconds? A lot of times, programmers have to face 500,000 lines of code, 800,000 lines of code, or more; why waste them 5 minutes here and there if they are looking for something else and not interested in reading the intersection code line by line?

But at the same time, my coworkers might even say, that he removed every single line of comments -- programmers should read code, not read comments.

Should software engineers write code for people to read? I can only think of 2 contrary cases:

1. If you write code that is easy for human to understand, that means the company can easily fire you. People who write code that are difficult to understand, the company needs them to stay.

2. If other people "read you like an open book", they may think you are weak. They may keep themselves hard to understand, to maintain their power.

Answer 1

Should software engineers write code for people to read?

Absolutely.

But what you're maybe missing is what the original quotes meant to say is:

Programs must be written for programers to read, and only incidentally for machines to execute.

Writing programs that laypeople can understand is not terribly useful, because laypeople aren't reading your code - skilled programmers are. # put data into 2 sets and get the intersection is not a useful comment, because it doesn't explain why the programmer is doing that. The code already tells you what it is doing.

The quotes say that the code should be clear about what it is doing as well. I can't say if the code you were looking at was clear or not. 17 lines isn't unreasonable to filter data and find an intersection. Honestly, 17 simple lines will usually do a better job being legible than 2-3 clever lines.

People also vary in their language fluency. Some are fluent in the language, while others are not. Some are fluent with functional or OO programming idioms, while others are not. Some are familiar with your codebase's patterns, while others are not. Writing your code to be readable to the lowest common denominator isn't ideal either since it adds noise that the experts need to discard to get at the meat of what you're trying to convey.

Like all things, these quotes are fine guidelines if you take them for what they are: pithy quotes that are good to follow in moderation.

Answer 2

Your assumption that writing code that is easy to read and understand makes it easy for you to get fired - and the obvious reversal, that writing code that is hard to read makes you hard to fire - is so wrong, it could not possibly be wronger.

Code that is easy to read saves the company money. Code that is hard to understand is an absolute negative. Guess what: if you wrote code that is hard to read, and I review it, it will be rejected. It’s not acceptable if I can’t easily understand and verify it. So you will have half or a third or a quarter of the productivity of another developer who gets it right the first time. And with your low productivity, you will be the first to be shown the door.

Now what if you got a position where you had the chance to write unreadable code for two or three years? There will be the point where you are found out. When maintenance costs grow. Because you can’t understand your own code. They’ll hire a better developer who will get through your code. He or she will curse you, but they will get rid of you.

Answer 3

Your first suggested reasoning for writing obscure code is often cynically called "job security". Another quote regarding this topic is this one:

If it was hard to write, it should be a pain to maintain and impossible to use.

I do not know whom to credit here, it is just one of those lines that stuck in my mind. I am afraid there is a lot of truth in it when in comes to explaining why there is so much obscure code around. Some folks may be reluctant to make it look too easy.

Introducing 17 lines of code with 2 lines of text is good in my book, even if it says just what and not why. It can make it so much easier and quicker to get your head around a large piece of code. One could argue wrapping those lines in an aptly named method would even be better, the point is it is always good to offer levels, hierarchy, divisions, modules, meaningful chunks, just like you use chapters, paragraphs, sentences and interpunction in text. It increases the ability of the reader to digest complexity.

You can skim the 17 lines and skip to the next comment, you may get by just reading a few comments to understand the code. That is a lot less required processing and a considerably smaller brain stack needed on the reader's part.

This is all independent of the necessity to write readable code, no one is claiming comments are there to compensate for poorly written code. And of course there is no point in commenting the bleeding obvious, like a comment over each line, the comment should summarize some compound.

Comments are a code smell

No they are not, not comments as such. The claim implies snobbism, as if a programmer who needs helpful comments will never be in the same league as those who can do without them. It is all about avoiding mistakes and preventing overlooks. We should not rely on the brain power of the next developer, a fair amount of logical reasoning ability with a limited comprehension span should do. Comments can make a big difference here.

Dismissing comments is like dismissing safety features in an industrial setting. They are just wasteful, right? Everyone should just watch their step. Keep their balance. Look where they're going... Get rid of those railings, traffic light, helmets, safety belts. All noise.

Answer 4

very often at work, I just read programs that have lines of lines of them, without saying what it tries to do. For example, I can be reading 17 lines of code, and wonder what the programmer wanted to do, and after a couple of minutes, only to found out it was just to filter out some data into 2 sets and get the intersection. The same thing could be done in 2 or 3 lines.

I wouldn't assume that it was done that way by design. Spaghetti code is often the unintended side effect of project concerns, e.g. limited time, or lack of competent resources.

programmers should read code, not read comments.

This is a common (and valid, IMO) saying. The intention is not to make you read 17 lines of obscure code without comments; the intention is for the programmer to write the code in a way where comments aren't necessary to understand it.

Consider these two examples. The first uses a comment to tell you what the code does; the second requires no comment.

Example 1:

//Find the intersection of two sets
Set<int> DoProcessing(Set<int> a, Set<int> b)
{
    etc....

Example 2:

Set<int> FindIntersection(Set<int> a, Set<int> b)
{
    etc....

See also WOC (Write-Only Code) vs. ROC (Really Obvious Code)

Answer 5

I have recently read below quote by Martin Fowler:

Any fool can write a code that computer can understand, Good programmers write code that human can understand.

I strongly believe in this quote that anyone can write a code that can be understood by computer. But it is very hard to write a code that human can understand. According to me, first line comment helps us to understand the logic behind that code. Else what happen is like you have to read whole code and then you can understand the logic behind it. I am not saying that you should put comments on each line but at the top you should out. I think it is good practice.

Answer 6

If we were meant to be writing code for computers, we would still be writing in machine code. The computer isn't helped at all by programming languages. That's all for the benefit of programmers.

I will point out that the first person who reads your code is always you. You can't easily tell what bugs are in your code, and can't easily fix them, not to mention add features, in messy code. As Turing Award winner Tony Hoare said, you want your code to be so simple there are obviously no deficiencies, not so complicated there are no obvious deficiencies.

As far as being irreplaceable, obtuse code is always the first target for being replaced. It's not generally hard to make a case to management to replace, because it contains so many bugs and is so difficult to add features to. People don't worry about preserving its exact behavior for the same reason. I'm willing to bet you replaced those 17 lines of set intersection code. I would have. How weak is someone's influence whose code no one wants to work with, and never lasts long term? That's a recipe for isolation and dissociation.