in Technology

Is Code Written To Be Read?

The other day I attended a tech talk hosted by Facebook. Their internal platform team was talking about how they manage the Facebook framework and code base.

The presentation was titled “Code Is Written To Be Read”.

Immediately my gag reflex kicked in. Code is written to be read??? Really??? I literally can’t remember the last time I sat there and thought “hmmm, how readable is this code, I wonder if so and so will be able to understand this”. Having said that, I think I was the only person from a startup in attendance, most were from Google, Zynga, and other larger tech firms. So perhaps I was the wrong audience for this topic.

Whatever their problem is, it is not mine. In my world I have one reason to write code – TO SHIP.

“Code is Written for Users to Use It” (i.e. just ship or shipping is a feature) – that is the startup equivalent mission statement.

And this is where all the “maintainability” coding trolls come in and leave comments like “yeah, but it’ll be huge advantage if we can iterate quickly and get a v2 out and so on and so forth, thus we need code thats easy to maintain”.


Here’s the reality – your product is likely going to fail, so if you wasted time and money making fancy abstractions, doing code golf, and focusing on elite coding craftsmanship… you blew it. You failed. You should have finished it 2-4 weeks earlier instead.

You have to EARN maintenance as a problem. You have to EARN v2. You have to EARN the right to practice expert craftsmanship. If you get there, if you really get to the point where maintaining your code base is a problem for you where many other developers are reading your code… congrats! You’ve succeeded. Go nuts, rewrite everything. You deserve it!! Forget every word I am writing, and go attend the Facebook tech talk and take diligent notes.

But for most of us, we are not going to earn that right. We are going to fail or pivot or leave or get acqui-hired or whatever. That code is going to get thrown in the trash never to be touched again. So how’s that clever FactoryOfTaskFactories abstraction feel now?

And that’s why you probably don’t want to hire Facebook or Google engineers for your startup. And more so, if you are a new grad engineer who aspires to be a startup founder one day, that’s why you don’t want to join Facebook or Google.

Look, it’s not that there is something wrong with those developers. I’m sure working at Facebook or Google is fantastic. It is the closest thing to a tenured prof position you can get in this field. The problem is that they operate under significantly different operating conditions than you do (unlimited money, unlimited time, lots of technical resources, working across massive teams, etc + MASSIVE scale problems, huge performance requirements,petabytes of data, etc). They learn a very different craft than you do.

Your craft, the startup developer craft, is simple – “get things done”. The other parts of the craft, you have to earn.

(caveat – if you are building a startup focused on platform or tools being used by other developers, your craftsmanship should be excellent)
(disclaimer – I have nothing against facebook or google, they are full of friends of mine and other wonderful and smart ppl)


  1. Good post Dan, but I don’t agree with your premise that “readable code” is the same as “fancy abstractions and code golf”…although I wasn’t there for the talk (so I’m going out on a limb here), I’d interpret readable code as “usable” code.  Just because you need to ship, doesn’t mean your code can’t be readable and easy for your colleagues to work with. If you’re a solo-entrepreneur then make your code as messy as possible, but if you’re not, then readability is crucial.

    I absolutely agree that there needs to be a focus on delivering code quickly and frequently, but the basics of readable code won’t slow you down, rather they speed you up. Common styles, the right programming language, consistent naming conventions, consistent indentation, smaller commits, grouping, and appropriate structures don’t cost any more time, but make a world of difference to how well the other coders in your startup can work with your code.

    It sounds like you’re arguing against “excessively clever” code – that I agree with. But I still support readability.

  2. Forget about v2, two weeks from now someone else is going to work on your code, and if they don’t understand it they are going to waste time figuring out what you left behind, but they won’t really get it, so they will probably  break what you did, and worse, the sum of both contributions is going to be even harder for the lucky 3rd visitor.

    I guess it depends on where you are on the scrappy scale. The same applies to what “adequate” code means.

    As usual, the answer is somewhere in the middle.

  3. some people can’t write bad code. Writing proper maintainable code leads to faster development. Please go and read “Code Complete”.

  4. Clearly you shouldn’t write bad code and be sloppy.  In fact you generally shouldn’t be coding if your grasp of the craft is rudimentary.

    But generally I often force myself to choose less saavy/clever techniques than I would if I were working under different operating conditions.

    To give some concrete examples (note that these days I’m writing very low level C where there are few libraries available):

    I’ll choose to write a simpler sort that is 3-5 lines of code.  It maybe O(n^2), but I know it will work and I can write it fast with few bugs, unlike if say I was using some clever merge/quick sort technique.

    Or I’ll use a linked list or array when a tree or trie or a more advanced data structure would have been faster, but resulted in 100+ more lines of code.

    Or I’ll use mysql instead of mongo because I know how to fix mysql faster and can code something working with mysql in a flash.  (note that in some of our heavy scale systems we have replaced mysql… but we had enough scale where we EARNED doing hard computer science).

    Or I won’t abstract, I’ll let my procedure be long (in fact I’d argue this will make it more readable, albeit less ‘maintainable/reusable’).

  5. I prefer to read jzw’s interview in Coders At Work.  Or the Joel Splosky article “shipping is a feature”.

  6. I emphatically disagree.

    Aside from a few exceptions, my opinion is that code MUST be readable. Oh, unless both of the following are true:

    Requirement #1: I never have bugs in my code. But it’s more likely to snow this weekend in the GTA. At the extreme end, TDD has been developed exactly for this reason, the theory being that more time is spent debugging than writing the original code, so if I can pinpoint the source of errors faster at the cost of more time up-front, I’m better off (not to mention refactor with confidence, and ensure fixed bugs don’t reappear).

    Requirement #2: I’m the only person that will ever look at my code. While that is a possibility, it’s going to suck that I wont be able to take holidays for the next 4 years. ;)

    I think if 2-4 weeks are going to impact whether or not I’m successful, I have larger issues. Don’t forget I’ll have to throw out all that unscalable, untested, spaghetti code after my first release…that might impact my timeline for v2, no?

  7. Clearly?!?!?!

    You just contradicted everything you just said in your article in your first sentence of your comment.

    Amazing how you change your tune when someone calls you out on giving horrible advice to a community of relatively in experienced developers.

    With this comment you have basically identified that your entire article was a brain fart that your crapped out onto the keyboard.

    Readable code has nothing to do with the ideal solution. 

    I think your overall message was, don’t worry about the ideal solution, worry about shipping something that works. If that was your message, it was entirely polluted by your statements of being completely reckless with your code for the sake of speedy delivery.

    Readable code is commenting where you don’t have ideal solutions, communicating what might be better if a refactor was going to occur. 

    Readable code is being explicit with what you are doing so that refactoring is straight forward.

    Readable code is about acknowledging that you will have to change.

    I didn’t watch the Facebook tech talk but I assume the whole point was to warn developers of the dangers of writing poor code and to put some thought into the readability of their imperfect solutions so that they won’t feel as much pain as the developers at Facebook encountered.

    I am not sorry if I offended you, I hope I did. I hope you are so offended that the next time you decide to write an article, you put some thought into what you are saying instead of defecating on the internet. 

  8. I think TDD has no place in the world of early stage startup.  

    But don’t take my word on it, read about netscape and how they launched a ho-hum successful company with no test cases – (you'll have to read the actual book or find the actual interview somewhere on the internet).

    Remember a fundamental rule of software engineering.  More lines of code = more time.  Test cases = more lines of code.

    Also, re: your last line.  You ARE going to throw out all your code.  If you fail you are going to throw it all out because you FAILED (very high probability).  If you are successful you are going to throw it out, because you have scale that you never dreamed of…

    Always assume that v1 is throw away.  Hence go fast and do less.

  9. Quit your job, have no income and build something that pays the bills.  

    Tell me how you feel about code quality while under immense pressure to just f’n ship and start making money…You’d be surprised at how “good” your code is when you just sprint and take shortcuts everywhere.  And by good I mean the real kind of good – “functional, stable, fast, etc”. Not the flakey “readable, will my buddies from Google respect my codez” good.

  10. what Dan said here is spot-on – least in my world. “…code is as code does…” to paraphrase Forrest….if you can’t ship, you cant’ eat….all else is not on point.

  11. You’re not arguing against  code readability here, you’re arguing against designing and implementing optimal or ideal solutions before the need.

    Your sorting routine may be simpler than a mergesort, that does not mean it’s not readable.

    A linked list may not be a very clever data structure, but it can definitely be implemented in such a way that it is readable, without slowing you down.

    Readability is not about implementing fancy abstractions or overly clever solutions. It is about adhering to conventions that make it easier to tell your intent when comes the time to revisit and refactor your original code.

    Your comments on Google or Facebook engineers and whether they would fit in startups are really puzzling. There is no shortage of Googlers or Facebookers who went on to join or start successful startups (ever heard of Twitter?). Also, it is well documented that Google established a strong engineering culture with a focus on code quality very early, when they were still a nimble startup and long before they became the behemoth that they are today. It looks like things worked well for them.

  12. Well, yes and no. For parts of code needed to “test out ideas and features”, sure. But except if you have a 2-3 months runway, there’s gotta be some code that will stay as the foundation of everything you’ll be testing, and yes I think this could should be readable. Except maybe if no one else ti go through the code…

Comments are closed.