Optimize for readability first. What slows down developers when reading code

http://va.lent.in/optimize-for-readability-first/

by valyard • 12 years ago

54 78 12 years ago

va.lent.in

chton• 12 years ago

I'm using "Optimize for readability first" from now on instead of the usual. I'm not sure if I'd call that 'optimization', but it definitely gets the point across a lot better, especially to newer developers.

barrkel• 12 years ago

The most common form of unreadability I see is overly abstracted code in Java, littered with patterns that obscure the kernel of logic, forcing you to do global code searches in order to see through all the indirections.

arethuza4• 12 years ago

I remember having to work on some J2EE based systems 10 years ago or so that were nothing but a vast (many many thousands of classes) collections of abstractions - actually finding the code that actually did anything was quite an exciting adventure. I swear one system had about 25-30 layers of stuff between Struts Actions and the underlying call to actually drop a message on a queue. Not helped by the need for whoever designed the system to use every single feature of J2EE even if really wasn't required.... CV driven development.

couchand3• 12 years ago

CV driven development

brilliant!

deong3• 12 years ago

I'll go even further and say this is essentially the only form of readability I care about. The article talks about things like "unnecessary one-liners" with the ternary operator as an example.

I don't care at all about one-liners, whether or not they're immediately understandable. If I'm trying to understand how to find a fix a bug or add a feature, then if, as the author did, assume that the obvious bad code things like meaningless variable names and spaghetti control flow aren't there, then the only hard problem is "where in the code does this thing happen". Make that problem easy to solve, and I can spare the 10 seconds it takes to understand a ternary operator. Hell, I can spare the 10 minutes it takes to understand some weird nested list comprehension. Stick a comment telling me what you're doing, and I may not even need to bother.

The same is true with low-level optimizations. If you need to do something clever, then comment it, and we're fine. Obviously one shouldn't go overboard, but I don't see anything wrong with the kind of premature optimization in which the programmer sits down and immediately knows of a fast way and a slow way to do something and chooses the fast way (within reason, of course, and that's a subjective judgment, but it's one I'm OK with).

Basically, make your code easy to approach. Make it as easy as possible for me to go from, "I need to change what happens when the user does X" to finding the code that governs that behavior. If all that code is in one tidy little location, then aside from the obvious need for good variable names, sensible whitespace, etc., write it however you like. I'll figure it out.

pkolaczk3• 12 years ago

Exactly! There is nothing wrong in complex code as long as it is isolated from the rest of the code and well documented in terms of its API.

jtymes• 12 years ago

I couldn't agree more. I came into development as an intern and it took me months to loosely wrap my head around how the code was organized.

Here I am 4 years later on the same codebase (a Swing-based application), and it is very difficult to hunt down bugs. Fixing them is often easier than finding the place in the code where it's happening, even if you know where it theoretically is.

FollowSteph3• 12 years ago

I'm sure it's been said many times before but the book Code Conplete 2 is a great follow up read to this article.

givan• 12 years ago

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

rectangletangle2• 12 years ago

I've recently begun digging into Haskell; it has a lot of interesting and novel features. However, I can't get over it's syntax. It often uses non-alphanumeric characters in place of function names. Many functions are poorly named, e.g., `elem` vs Python's `in`. I strongly prefer the more natural English style syntax; even when you know a language well, it reads faster. That being said, Haskell is awesome for numerous other reasons.

500 line functions are the devil, they're harder to read, test, modify, and reason about. They tend to encourage code that isn't DRY, or reusable. The only benefit they have is an almost always insignificant performance boost, at the cost of everything else.

Also magic isn't terrible if it's used in moderation, and it's well documented. Though it usually results in things being substantially harder to GREP.

arethuza4• 12 years ago

"I can't get over it's syntax"

I think there is a syntactical pain barrier for a lot of languages. However, once you are through that barrier you stop noticing the syntax.

e.g. When I first looked at Python I remember thinking "significant white-space - that is evil". However, I forced myself to write some Python and after a fairly short time I didn't notice that aspect anymore and now I think significant white-space is actually pretty sensible.

I've had similar experiences when starting out with Common Lisp, PostScript and a variety of other things that don't look like a variation on C.

I would agree that Haskell does look a bit weird - but everything looks weird the first time you see it. Indeed, I can remember seeing C for the first time when I was 16 or so (early 80s) and thinking that looked weird compared to the Basic I was used to...

rectangletangle2• 12 years ago

I agree for the most part; with persistence it can be overcome. But why make anything harder to learn than it has to be? `long_descriptive_variable_name` gives you a lot more useful information than `:++-`. What's the benefit of making a language look like runes? For this reason alone, I find LISP to be easier to read.

seanmcdirmid9• 12 years ago

I think there is a syntactical pain barrier for a lot of languages. However, once you are through that barrier you stop noticing the syntax.

No, not always. Some languages are intrinsically worse with terseness than others; for example: APL, Perl, and Haskell. The association fallacy is so useful :)

cousin_it• 12 years ago

I think line noise operators and single character names are bad in any language. Haskell is among the worst offenders, but C++ isn't much better. At some point this frustrated me so much that I started making my own language. Semantically it was pretty much a dialect of ML, a statically typed, eagerly evaluated language with mostly immutable data, but syntactically it aimed for extreme readability:

1) All keywords and standard functions have full English names, no abbreviations.

2) Keywords are UPPERCASE, types are Capitalized, values and functions are camelCase. Easy to tell the difference at a glance.

3) Mandatory type declarations everywhere. Limited type inference within expressions, but that's it.

4) Only one kind of syntactically significant parentheses, instead of () [] {} <> as in C++ or Java.

5) No two-character operators. Instead of x != y you have to write NOT (x = y). Sorry!

6) Significant whitespace.

The code looked something like this:

    GENERIC(Type) FUNCTION identity(value: Type): Type
      RETURN value

I have a lot of code written in that dialect, just for my own amusement. It's pretty verbose and boring, but extremely easy to write, impossible to misunderstand, and sticks to memory like nothing else I've ever tried. I still want to finish an implementation someday.

yogsototh• 12 years ago

For the syntax, this article might help you:

http://blog.ezyang.com/2011/11/how-to-read-haskell/

I personally continue to find many Haskell library code hard to read. But if you make some effort you own code can be quite readable.

Unfortunately I don't know if there is any guideline to make your Haskell code more readable.

For example, I'll be glad to get some advices regarding the following questions:

- When to use type synonyms/data/records/tuples/lists for containers?

- How to name your variables, type variables?

- When to split your code between a long one-line or many small named functions?

- When to split your code in many different modules?

- etc...

VeejayRampay4• 12 years ago

I've always thought that what makes code hard to read is the fact that several persons are usually working on it. Beauty is in the eye of the beholder as we all know. Some developers like snake case, others prefer camel case. Some prefer 4-space indentation, while other can't stand it and much prefer 2 spaces. Some like braces on the same line, some others prefer it on the next line.

What really bothers me is that editors in general force people to share a codebase formatted for a given style that may or may not satisfy everyone.

And the worst is that I don't see why that has to be. Ideally "code" would be some form of abstract syntax tree and the editor would apply a user-generated "stylesheet" on top of it to display the code as the user wants to see it.

Upon save, all the style would go away and only the abstract representation of the code would go to the shared repo.

Not an easy thing to make happen for sure, but that'd be awesome.

KiwiCoder2• 12 years ago

The problem is that coding style goes deeper, it goes right down to the abstraction.

VeejayRampay4• 12 years ago

You're absolutely right. It's about design more than anything else, but at least for the cosmetic details, I feel the current state of affairs is sub-optimal.

valyard5• 12 years ago

If you work in a team you absolutely MUST enforce a coding standard. It better be a community standard most of developers use. All team members must use either tabs or spaces and have IDE configured to automatically apply styles.

It will save A LOT of time later.

VeejayRampay4• 12 years ago

I (respectfully) disagree. The editor should take care of adapting the codebase to the standards the programmer likes. Trying to force 20 developers into a "consistant" style only makes room for a soft consensus that doesn't satisfy anyone in the end.

If we can do it for web pages (with CSS) there's no reason why we couldn't be able to do it for a source file.

seanmcdirmid9• 12 years ago

Use a proportional font for code reading! I really can't stand reading archaic type writer fonts anymore that are only optimized for ascii art.

robert_tweed2• 12 years ago

The problem with that is that it doesn't work when you have code (and comments) formatted in neat columns. Since plain text doesn't have any portable way to handle tabstops, everything has to be padded out (after the initial indent) with extra spaces. Characters must have equal widths or nothing lines up properly.

This is pretty common in long repetitious declaration blocks, at least when the code is written by someone that cares about formatting. It vastly improves readability. Example:

   int   some_variable     = 100;     // Foo
   float another_variable  = 1000.0;  // Bar

The gofmt tool actually does this kind of column formatting automatically.

morsch3• 12 years ago

Kind of strikes me as something the editor could do ad-hoc. Maybe the tab character could return to let programmers tell the editor to align the adjoining lines according to the tabs. Would work well at least in your example.

seanmcdirmid9• 12 years ago

The problem with that is that it doesn't work when you have code (and comments) formatted in neat columns.

I mentioned ascii art as something that fixed-width type writer fonts are optimized for.

klibertp8• 12 years ago

http://tvtropes.org/pmwiki/pmwiki.php/Main/BigNo

Of course, once you implement an editor which does a good job of keeping things aligned even when using proportional fonts, I'll switch immediately. It's not like I didn't try - default font in Pharo is proportional and I tried working with it for a few weeks. Smalltalk syntax is so clean and minimal that I thought it would be ok, but even there I had to change the font to monospace - in the (few, like populating a dict, writing to a stream, things like this) instances where I wanted the code to be aligned I couldn't do this and it was too irritating for me.

DanBC2• 12 years ago

May I ask: what is being aligned here, and why does it fail?

Aligning stuff to a left margin / tab-stop / 4 space set should be easy, no?

And are there any non-monospaced fonts that are designed for programming?

stinos• 12 years ago

When by Go to Declaration you get to an interface or an abstract class and have to figure out what implementation there might be used. It gets worse with Dependency Injection,

This seems far-fetched to me and doesn't have much to do with readability anymore. Moreover most of the time this is imo how code should be. If you start programming with readability in mind and as such start throwing away standard design practices because they lead to one more click or less readability, you are doing it wrong. That comes dangerously close to using copy-paste instead of a function because it is clearer since you can see the implementation directly. I'd argue that you should not have to figure out what the implementation is. That's the whole point of using interfaces (and dependency injection for that matter) - if you have to figure out what implementation used then you are either the implementer or the code is wrong somehow, like it is violating substitution/dependency inversion principles. Or you are studying the code in-depth, in which case you have to go through all implementations anyway. Calling all that 'readability problems' is a bridge too far.

jeremyjh• 12 years ago

When you are searching for a bug, you do need to understand the implementation. Of course by definition something is "wrong". Calling a function is fine by the author since you can easily jump to its definition. But if the actual function call is determined at run-time based on XML configuration, then you first need to figure out how that fits together for the particular case you need to investigate.

valyard5• 12 years ago

OP here. You both are right. I'm not saying that DI and interfaces are bad. Of course not. I'm just trying to find a balance between modularity, loose coupling and code graph connectivity. Of course it's not just black or white.

couchand3• 12 years ago

In a case like this, you really ought to have a standard set of unit tests that covers the contract of the interface. If you run that against all the implementations and none of the tests fail, the bug just isn't in the implementation itself and you can safely move on to looking for integration issues. Of course, if the unit tests for the interface are incomplete you can't rely on them, but in that case you've built yourself a leaky abstraction that you should go back and look at before doing any more systems testing. Effective dependency injection simply requires comprehensive unit testing.

annnnd• 12 years ago

This is a great write up and should be necessary read for every novice (and not so novice) programmer.

That said, I would compose list "What makes code hard to understand?" differently:

  1) improper naming of functions / variables (if you can't name it properly, you can't develop it)
  2) excessive documentation where not needed (document only non-obvious stuff)
  3) *complex* one-liners (because simple one-liners actually help readability)
  4) and 5) can stay. :)

The main point is valid though. I would phrase it like this: optimize for correctness first, readability close second, and don't optimize for performance until you can identify the significant gain (always by measuring it!).

valyard5• 12 years ago

I don't mind improper naming because all the functions are essentially just nodes in code graph. Of course it helps if you can figure out what they do just from their names, but you have to read code anyway.

Same for excessive docs. Sometimes you can find huge walls of text before every function, or meaningless javadoc comments which say that function GetData "returns data". But those are usually needed for 100% docs coverage which might be enforced by corporate policy.

cessor3• 12 years ago

In a study that I did I found that bad naming makes people approximatly 15% slower. The comparison was between single name identifiers, abbreviations and "normal" words. Have a look, you might have to translate it though...

http://www.cessor.de/empra13

Cleaned up data linked as a spreadsheet at http://www.cessor.de/antwortdaten

deong3• 12 years ago

Of course it helps if you can figure out what they do just from their names, but you have to read code anyway.

This is, I think, the root of the (very minor) disagreement I have with your article.

I really don't want to have to read the code anyway. There may be 250,000 lines of code in a moderately sized system. If I have to read a significant fraction of them to figure out what's going on, that's the biggest sin you as the original developer can commit by a couple of orders of magnitude.

I want it to be obvious where to look for the code that controls whatever it is I want to change. If you make it easy for me to find those 50 lines of code, I don't care if you write them in assembler. 50 lines of anything are vastly easier to deal with than 250,000 (or god help you million) lines of the absolute best thing you can write.

jamesbritt• 12 years ago

TFA quotes Premature optimization — everything one tries to optimize before profiling and running tests on a working system.

Perhaps that same thinking needs to apply to readability. Premature readability—everything one tries to improve readability before running tests.

Readability seems a lot like pornography[0]; people claim to know it when they see it (or, in this case, when they don't) but are hard-pressed to offer a well-defined or objective description.

What we get instead are well-meaning but subjective prescriptions.

Shouldn't the alleged gains of readability practices be held to same measuring requirement as optimization?

Are there solid, objective studies on what makes code more readable? In a small group it might be best to have a discussion about coding practises to achieve some consensus, but if that's not feasible then some guidelines based on research would help.

0: http://en.wikipedia.org/wiki/I_know_it_when_I_see_it

cessor3• 12 years ago

Making use of "chunks" makes code better to read. A function is essentially a proper chunk (whereas a comment is a bad way to do the same thing). Depending on the paradigm, I usually enjoy code that has tiny units, but many of those - i.e. a function with 100 lines is harder to read than 100 functions with one line each. Ideally each name adds proper meaning to the code so that the intent becomes clear. Code like this is usually easier to change, reuse and test (tdd).

This can go the wrong way - many people mentioned how too many abstraction layers in big java projects are a pain, and I agree, as they often make the code more meaningless and abstract, rather than concrete. Oh yeah and pattern names do the same thing.

ajuc4• 12 years ago

i.e. a function with 100 lines is harder to read than 100 functions with one line each.

I understand where you come from, but I disagree with that particular example. 100-lines long function is harder to read than nessesary, but can be understood without problems.

100 functions doing the same work will be a nightmare to keep in head at once, at least for me. If you refactor one function into 100 you're not doing it right.

klibertp8• 12 years ago

In this case (of 1 function split into 100) each of them is probably used exactly once. The effect on readability, especially if they are defined in an order of execution, is similar to placing a comment (function name and args and return value) next to every single line in the 100 line function. No matter if the comment was actually needed or not there. So I agree, it will probably result in worse readability than keeping the function as one, but commenting sections of it and extracting only repeated patterns into separate functions.

gr3yh47• 12 years ago

"Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it." by Brian Kernighan

this is one of my favorite quotes ever

vrybas1• 12 years ago

I'm getting closer & closer to make this statement a rule:

"Code need to be that good - no one in a team can write any better"

If you, knowing current requirements, wrote a perfect code - it will still become messy at some point. Feature by feature new things will appear here and there. Functions size will grow, this CASE statement will grow etc. But still the "core" of it will be strong.

If you, knowing current requirements, deliberately wrote a "good enough" code, what will happen with next change? The code won't survive it and will be deleted(at best case). Therefore, bad code is completely useless from the start.

grymoire1• 12 years ago

In the 1980s, someone wrote an essay promoting "throw-away" code. Essentially he said every module (a) should be small in size, and (b) should have documentation that describes what the module does.

Someone maintaining the code then has the option of keeping the interface, deleting the code and re-writing it, rather than try to understand the thought process of an overly clever programmer. I've always found this useful when I write code others have to maintain.

joshka2• 12 years ago

An additional point that solves some of this - learn the difference between declaration and implementation. Think, why you care about the declaration? Why would you generally want to navigate to the declaration instead of the implementation.

The shortcut keys are similar, but just a little bit extra to navigate to the implementation over the declaration. Ctrl+F12 instead of F12 in Visual Studio, Ctrl+Alt+Click instead of Ctrl+Click with Resharper. Even easier, your IDE may support changing the default keybindings.

pkolaczk3• 12 years ago

"[Scala] is essentially a write-only language (please don't quote me on this!); "

I'm sorry, I quote you on this.

If you ever compared Hadoop codebase (Java) with Apache Spark codebase (Scala) you'd know this is BS - Spark code is order of magnitude more readable and easy to understand compared to Hadoop. Lack of side effects and lack of low-level mutable shared state protected by locks everywhere are two of the many reasons.

Of course, you can write terribly unreadable code in any language, and probably those academic languages with rich functionality and expressiveness make it a little easier to abuse features, or to choose right features for the job. But on the other hand I'd argue they make it easier to write readable code, once you care about readability and learn how to do this. Writing readable code is a skill you have to master. It is not something that comes for free in no time.

Optimize for readability first. What slows down developers when reading code

Related Stories