4

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.

nonopolarity
  • 1,827
  • 1
  • 16
  • 30
  • 2
    Possible duplicate of ["Comments are a code smell"](https://softwareengineering.stackexchange.com/questions/1/comments-are-a-code-smell) – Doc Brown Aug 05 '19 at 16:49
  • 1
    Possible duplicate of [Should you write good documentation and clean code to increase the "Bus Factor"?](https://softwareengineering.stackexchange.com/questions/111846/should-you-write-good-documentation-and-clean-code-to-increase-the-bus-factor) –  Aug 05 '19 at 18:52
  • 8
    Both 1. & 2. are pretty f'''d up mindsets; you don't want to nurture such attitudes (in yourself and others), and you don't want to work in such companies. – Filip Milovanović Aug 05 '19 at 22:02

6 Answers6

12

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.

Telastyn
  • 108,850
  • 29
  • 239
  • 365
  • 3
    I disagree about 17 lines of code without a single comment being better. There could be a thousand files in the project, without any explanation of intention. Here it is doing bit manipulation, there it is setting j, and increment i, until i + j - k is less than n. You really don't know what the programmer was up to. Doing so, is kind of like not naming the function FindMedium(), but just naming it XYOSudaoiduaosdha(), and say, yeah, read the code and you will know what the function does. It doesn't have to have a name to tell you what it is aiming to do. – nonopolarity Aug 05 '19 at 17:30
  • 6
    @太極者無極而生 - Yes, it does actually need to have a good name to tell you what it is aiming to do. That is the point. Legible code is legible because it has good descriptive names and is organized in a reasonable manner. _Not_ because it has comments. – Telastyn Aug 05 '19 at 17:56
  • 2
    @太極者無極而生 & Telastyn - Just wanted to say: generally speaking, yes, but sometimes there may be a technical reason to write code in a certain way that ends up being less readable or understandable (e.g. some necessary hack, or for performance reasons); and in such cases a clarifying comment may be valuable if there is no better option. – Filip Milovanović Aug 05 '19 at 21:58
  • @FilipMilovanović - absolutely. – Telastyn Aug 06 '19 at 00:33
  • @FilipMilovanović: Agreed as well, but the comments still need to explain *why* the code looks the way it does, and not reiterate what the code is doing. Even if the code is ugly out of necessity, we still need to name things well. – Greg Burghardt Aug 06 '19 at 12:21
  • 1
    @GregBurghardt: Yes, I agree; there's a bit of ambiguity in what we mean by "what" / "why" when we talk about these things, so maybe a better way to express it is, if you feel you need to add a comment, don't reiterate the individual steps (the "what" - people can read that from the code), but add something that explains what the *intent* is ("what it actually does", the "why"). – Filip Milovanović Aug 06 '19 at 13:07
  • Every failure to show intent with a good name should result in a comment. Every failure to show intent with a comment should result in a beating with a wet noodle. Ever failure to avoid commenting when a good name would have sufficed should result in a beating with a wet noodle. Ever beating should result in learning. That's what code reviews are for. – candied_orange Aug 08 '19 at 02:08
  • Every time I sit down with one of your code files it should tell me the story of your intent. The intent should be as closely tied to the code that (hopefully) fulfills that intent as possible. Names are very closely tied. Comments are loosely tied. Documentation is tied to another dimension. Used them all but realize what you're putting me through. – candied_orange Aug 08 '19 at 02:08
  • @GregBurghardt: There are exceptions though. For example, contrived regexes warrant comments that simply explain _what_ the regex is looking for, and not necessarily _why_ (not saying it can't be added as well) – Flater Sep 17 '19 at 08:32
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.

gnasher729
  • 42,090
  • 4
  • 59
  • 119
  • Unfortunately, I know a few friends who deliberately wrote obtuse code so they'd be more necessary. They still got fired eventually. – user949300 Aug 06 '19 at 05:04
  • A lot of programmers in the industry (in Silicon Valley or up in Seattle / Redmond) only work 3-5 years. Some even just 1-2 years. By the time people don't like their difficult code, they might have or ready to leave the company by their own choice. – nonopolarity Sep 17 '19 at 08:52
  • The assumption is only wrong in a company that has *competent* IT management focussed on long term improvement. There are quite a few dysfunctional companies where the assumption would be entirely correct. – Michael Borgwardt Sep 17 '19 at 11:12
2

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.

Martin Maat
  • 18,218
  • 3
  • 30
  • 57
  • Comments are code smell not because weaker programmers needed them to understand the code, but rather because well written code should make most comments looks redundant. If a comment is needed to make some code understandable, that is not the fault of the programmer who had to read the code, but rather it is the author of said code that has not made their code sufficiently clear. Of course there are times when you had to write code that's naturally hard to understand and less readable than ideal, when doing optimisations for example, in which case adding comments can certainly help. – Lie Ryan Aug 06 '19 at 04:24
  • 3
    Adding comments to a crappy code is like adding warning sign boards where safety railing should have been necessary to prevent falls. Railings are clean code that are designed to actually prevent falls and be obtrusive enough to indicate falling hazard, instead of warning boards that can easily be missed. – Lie Ryan Aug 06 '19 at 04:35
  • @LieRyan spoken like someone who has never inherited code. Comment basic functionality and error traps always. Clean Code may be well made railings. But comments are the bolts that make sure someone doesn't move/remove those railings in necessary areas. even if those railings are actually warning boards, you don't want those removed either if you dont have the time to install new railings. – IT Alex Sep 18 '19 at 14:05
1

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)

John Wu
  • 26,032
  • 10
  • 63
  • 84
  • your example 1 and 2 are making it to look silly. The comment, as well as good function name, is to tell the intention, or the overall meaning to anybody reading it. If you say, use comment and name the function `DoProcessing`, you are distorting what is wanted and just uglifying comments. Of course you can uglify anything. – nonopolarity Sep 17 '19 at 08:55
  • The point of the examples is to illustrate a concept, so naturally it draws a contrast between the two by exaggerating them. That is the point. That being said, I have actually seen production code this bad in some cases. – John Wu Sep 17 '19 at 15:02
1

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.

Ishan Shah
  • 339
  • 1
  • 9
  • I have seen more junior programmers wrote line after line, and then later on, it was clear she was only doing an intersection of two sets of data with some filtering criteria. She might almost have written in machine code, and some people said, "code is code" but it wastes a lot of time to read her 17 lines of code just to understand what her intention was at the time. Another example was in the old days with GOTO statements and nowadays with code that has `break` or `continue` peppered every where. Machines can understand that, but human cannot do so well. – nonopolarity Sep 17 '19 at 08:41
0

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.

Karl Bielefeldt
  • 146,727
  • 38
  • 279
  • 479