Is Code For Computers or for People?

Question

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

Answer 1

Missing item: comments.

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

Answer 2

Yes.

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

Answer 3

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.

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?

Answer 4

Don't use hungarian notation in a typesafe language.

Answer 5

Hi,

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.

Answer 6

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

Answer 7

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.

Answer 8

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.

Answer 9

“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:

• coding-style
• best-practices
• refactoring

Answer 10

I would recommend taking a look at Clean Code by Robert Martin. It's a great guide on how to make your code more readable and, well, clean.

Answer 11

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.