31

Ultimately, code compiles down (eventually) into instructions for a CPU. Code, however, (in my humble opinion) is for human beings to read, update, and interact with. This leads me to the following observation:

Code that is unreadable by other engineers, even if it's functional, is bad code.

With that in mind, what can this programmer do to make code more easily read by humans?

  • Naming Conventions? (Joel has a fair amount to say on that one)

  • Code Structure/Layout? (please, for the love of god, don't get into the { placement debate)

  • Phrasing? (Is it possible to write code that looks more like the English language)

Are there good articles out there beyond Joel's.

Chris
  • 44,602
  • 16
  • 137
  • 156
haseman
  • 11,213
  • 8
  • 41
  • 38
  • I would recommend taking a look at [Clean Code](http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882) by Robert Martin. It's a great guide on how to make your code more readable and, well, clean. – Logan5 Jun 01 '09 at 19:05

10 Answers10

69

Yes.

If the computer doesn't run it, it's broken. If people can't read it, it will be broken. Soon.

S.Lott
  • 384,516
  • 81
  • 508
  • 779
Charlie Martin
  • 110,348
  • 25
  • 193
  • 263
51

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” -- Martin Fowler, "Refactoring: Improving the Design of Existing Code"

But since you've already reached that conclusion on your own, suffice to say that this is a huge topic. It's not something you'll be able to get a single answer on. Making your code maintainable is not limited to coding style, but also involves your overall design as well as your construction process. Here's some tags on this site where pretty much all the questions and answers will impinge on this topic:

Community
  • 1
  • 1
Adam Bellaire
  • 108,003
  • 19
  • 148
  • 163
  • 2
    In writing "Any fool can write code that a computer can understand," Fowler is probably alluding to Silvanus Phillips Thompson's *Calculus Made Easy*, which refers to "fools" throughout the introduction, including the famous line "What one fool can do, another can," which has been referred to by both Martin Gardner and Richard Feynman. – outis nihil May 12 '14 at 19:29
29

Programs should be written for people to read, and only incidentally for machines to execute.

-- from "Structure and Interpretation of Computer Programs" by Abelson and Sussman

jalbert
  • 3,047
  • 2
  • 20
  • 21
  • 1
    Too many people misinterpret this as: code is read more times than it is executed. – user51568 Feb 07 '09 at 11:48
  • 3
    No, I think its meaning is clear. Also, you should write code readable not only by others, but also by the future you who will be reading the code after some time (and will have forgotten every unwritten detail about it). – Luka Ramishvili Nov 24 '12 at 09:37
16

The compiler doesn't care whether your code is cleanly written or unreadable mess -- as long as the syntax is correct, the code will compile and it will run.

However, when it comes to maintenance of the code, cleanly written code for people is going to be very useful. From a business case standpoint, the shorter it takes to understand the code for a new programmer, the less money is required to bring the new person up to speed. Therefore, cleaner code has more worth. What's the point when unreadable code performs 5% faster when it will take 100% more time to understand by the programmer? After all, programmers cost quite a bit of money.

Writing code following coding standards for style, variable naming, and such is important in keeping the code written by multiple people to be consistent. A consistent codebase following a good coding standard is going to be more maintainable.

Often, when it comes to optimizing code, it can turn into a unreadable mess, but generally, compilers have become better these days at optimizing, so having more clearly written code will also improve the chances that the compiler will catch certain constructs and perform optimizations on it, leading to improved performance.

Write for people, not the machine.

coobird
  • 159,216
  • 35
  • 211
  • 226
5

My take on it is a bit tangential - it's not about readability, it's about maintainability.

Reading is just looking at the code and thinking you can read it. It is usually assumed that, to be readable, it has to be readable to someone who has put no effort into understanding it.

Maintaining is making changes to fix bugs or implement new / changed requirements. Reading is just part of that process. I don't know of any maintainable code that doesn't require a learning curve on the part of the maintainer, and to someone who has not climbed that curve the code looks "not readable".

At the same time, I think it is part of a programmer's responsibility to teach the maintainer to help them climb the learning curve. One way to do that is to leave step-by-step instruction on how to perform the kinds of future changes that could be anticipated.

I often see code that is puffed up with whitespace so less of it fits on the screen, and given verbose naming and gabby comments. This gives the impression of readability.

Mike Dunlavey
  • 40,059
  • 14
  • 91
  • 135
5

Roedy Green wrote an extensive guide called: Unmaintainable Code.

"With that in mind, what can this programmer do to make code more easily read by humans?"

Answer: Read this guide and apply the reverse of everything it says to your development activities.

Quote from the general principles section:

"To foil the maintenance programmer, you have to understand how he thinks. He has your giant program. He has no time to read it all, much less understand it. He wants to rapidly find the place to make his change, make it and get out and have no unexpected side effects from the change.

He views your code through a toilet paper tube. He can only see a tiny piece of your program at a time. You want to make sure he can never get at the big picture from doing that. You want to make it as hard as possible for him to find the code he is looking for. But even more important, you want to make it as awkward as possible for him to safely ignore anything.

Programmers are lulled into complacency by conventions. By every once in a while, by subtly violating convention, you force him to read every line of your code with a magnifying glass.

You might get the idea that every language feature makes code unmaintainable — not so, only if properly misused."

While it's a firmly tongue in cheek, it is actually a very useful list (apart from the obnoxious ads) of what to avoid if you actually care about writing readable / maintanable code.

Ash
  • 60,973
  • 31
  • 151
  • 169
4

<sarcasm> Code only has to be read by a machine. So long as the end result fulfulls the user's need, it doesn't matter what the code looks like.</sarcasm>

Now maintainable code or code that can change, that's a completely different story.

Would you build a house with a plan scribbled on the back of a napkin, or throw away the blueprints after you're done building a house you might want to add a room onto one day?

Chris Ballance
  • 33,810
  • 26
  • 104
  • 151
  • 2
    -1: All code gets maintained. – S.Lott Feb 07 '09 at 01:19
  • No kidding? Perhaps you noted a *hint* of sarcasm in my tone... – Chris Ballance Feb 07 '09 at 01:24
  • 7
    @Chris, actually, no...I didn't detect the sarcasm either. It's not obvious from your first paragraph (imho) that it's intended sarcastically. I guess your point is that all code is maintained, as S.Lott mentioned, but as the first paragraph reads, it implies otherwise (to me.) – Beska Sep 18 '09 at 15:09
2

Don't use hungarian notation in a typesafe language.

Dave Van den Eynde
  • 17,020
  • 7
  • 59
  • 90
  • 2
    Apps hungarian and Systems hungarian are very different. There's nothing wrong with Apps hungarian, and it can be very useful in many situations. Nothing wrong with systems hungarian either...but it's limitations are great. – Robert P Feb 07 '09 at 01:11
  • In a typesafe language, the language sets the type, and the hungarian prefix will start to get out of sync in the long run. That's what's wrong with it. – Dave Van den Eynde Feb 07 '09 at 01:19
  • Hungarian notation should be banned except in Visual Basic (note keyword BASIC). – Kredns Feb 07 '09 at 01:25
  • 2
    Hungarian originally meant prefxing variables for business logic reasons, eg screen_x,screen_y and window_x,window_y Unless you are going to make a different integer class for each of these the labguage doesn't help – Martin Beckett Feb 07 '09 at 01:26
  • 7
    The original purpose of Hungarian notation was to add semantic type information to variables (i.e. "cb" prefixe for a buffer size, etc.), *not* to replicate data type information. This is what's referred to as apps vs. system hungarian. – Rob Feb 07 '09 at 01:28
  • 1
    Don't use hungarian notation. Period. In any language ... stepping off my high horse... – Tim Scarborough Jun 01 '09 at 19:16
  • 1
    Please do not use hungarian notation in and language. I fought lots of fights to get rid of it in PHP. PHP is typeinsafe language. Example Why write strFirstName when firstName is surely a String;-) – Gizzmo Dec 08 '15 at 13:53
2

my take on this is that everything is relative.

When you need to change code, the code is for you, when its executed its for the machine.

If a code is functional it has the potential of being read.

The human and cooperative being in you should make it easily readable to other humans, but ultimately, conventions aside, the readability of code might sometimes be in the eye of the beholder.

The easier the code is to be read by people, the easier it can be changed and maintained, since evolution benefits from the number of contributions/contributors you apply to a problem, this type of code can be declared better than unreadable code.

But ultimately, the code is to be made into a set of instructions to the machine.

Human intentions translated into something the machine can follow, so the code is for both , one at a time.

Ric Tokyo
  • 6,577
  • 3
  • 30
  • 48
1

Missing item: comments.

Even if the code is perfectly legible to its author, it might not be for everyone.

  • 9
    You should write code in such a way that it can be understood without comments. Comments should be used sparingly and only when really necessary. Too many comments can be more unreadable than too few. – tvanfosson Feb 07 '09 at 01:39
  • Use comments when you anticipate your reader cursing your name under their breath or being dumbfounded by a choice you made. – thebearingedge Aug 16 '23 at 10:26