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.

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.

  • 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. – nopole Aug 5 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 5 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 5 at 21:58
  • @FilipMilovanović - absolutely. – Telastyn Aug 6 at 0:33
  • 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 6 at 13:07
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.

  • Unfortunately, I know a few friends who deliberately wrote obtuse code so they'd be more necessary. They still got fired eventually. – user949300 Aug 6 at 5: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. – nopole Sep 17 at 8: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 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.

  • 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 6 at 4:24
  • 2
    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 6 at 4: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 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)

  • 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. – nopole Sep 17 at 8: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 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.

  • 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. – nopole Sep 17 at 8: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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.