Understanding your own code

January 5th, 2013 at 2:27 pm

I recently ran into a statement that left me very perplexed. A programmer was proudly declaring that he can’t understand every piece of code he wrote a week ago. I honestly tried to figure out where the pride comes from, but I can’t. Is he proud that he writes so much code every day? That anyone is willing to pay him to write code?

Let me state my opinion on this matter clearly up-front: not being able to understand the code you wrote a week ago, or a year ago, is unforgivable for a professional programmer.

There, I said it. And now allow me to elaborate. I’ve been programming seriously for around 15 years now. At some point relatively early I adopted some programming practices that have been with me ever since. I can still easily understand code I’ve written a year ago, two years ago or twelve years ago. Code in various programming languages, covering various domains. Algorithms, parsers, web apps, embedded controllers, scripts, linkers, you name it. Even if I look at earlier code, while it’s more difficult for me to understand, I can recognize that some patterns already started to emerge.

The main practice enabling this is realizing that code must be readable. Readable by you, readable by others. Code that isn’t readable is as bad as, or worse than code that doesn’t work. And if you can’t understand your own code after some time, there’s no chance someone else will be able to understand it, ever. That’s not a product of your effort to be proud of.

I can’t stress enough how important it is to be able to read and understand your own code easily. Not only because it makes it a generally better product, maintainable by others. Also because your code is your personal toolbox, one you will use and reuse over and over during your career. Having such a toolbox is extremely empowering, and is one of the most distinguishing features of experienced programmers. I can’t count how many times my problems were immediately resolved by recalling that I faced something similar in the past, digging through my own code archives and finding a solution, or something resembling it. Obviously, code you don’t understand can’t take part in such a toolbox.

It would be unfair to finish this post without at least trying to explain how this feat can be achieved. Frankly, it’s not easy to put in words, but I can try.

I’m pretty sure it’s a trick also used by writers (and probably practitioners of every other creative profession). Once you’ve written some piece of code (the smaller the better), you have to stop and figure out if it’s readable and understandable. Read and re-read it, several times. Try to detach from your current stateful understanding of the problem, imagining someone who is reading this code without all the useful context you currently have in your head because you’re writing it. Would such a person understand it? If not, why not? Don’t hesitate to use every trick in the “code readability” toolbox taught by books like Code Complete, until you’re confident that the code is understandable.

And once you’re happy with the result, read it again. And again after a couple of days. This reminds me of writing the deeper technical articles for this blog; for each sentence I write, I read 20 and rewrite 5. Often this is also true of the code I write. Perfection can be achieved either by a gift in your genes, or by ruthless practice and iteration. Since I was not possessed with the former, I stick by the latter.

Finally. refactor and improve fearlessly. If you run into a piece of code that could be clearer, make it clearer. Improving code quality is one of the subtle side-tasks of our profession. It’s one whose benefit is sometimes difficult to quantify, but after you’re involved in one or two multi-year multi-person mega-projects, you just understand subconsciously.

Related posts:

  1. Understanding the x64 code models
  2. understanding web programming & design with PHP / XML / XSLT

50 Responses to “Understanding your own code”

  1. ripper234No Gravatar Says:

    “not being able to understand the code you wrote a week ago, or a year ago, is unforgivable for a professional programmer”

    Then I guess you won’t forgive me :)

    I like writing readable code. There are few programming activities I enjoy more than refactoring … it’s very satisfying.

    HOWEVER, and it’s a big however, there are other constraints. Have you ever worked at a startup? Sometimes you just don’t have the time. Often you’d rather push that one extra feature or fix that little bug now, rather than document or refactor, because an hour of your time now is sometimes worth five or ten hours a year from now. You don’t know if you’ll get the next round of funding. You don’t know whether you’ll be able to get any customers. Heck, you don’t even know if the feature you’re working on right now won’t be totally scrapped in two weeks.

    You need to spend your time now fixing the business’ most critical pain points, and doing some extra work to save time for you, or other people, in the future (when they revisit this piece of code), is not always the smartest choice.

    I’m not proud of it when I find it hard to understand code that I’ve written. The perfectionist in me cringes in pain. But the pragmatic in me accepts it. It takes experience to recognize just how much refactoring is enough per case … and sometimes the answer is “very little”.

  2. Jörg SeebohnNo Gravatar Says:

    I agree with you wholeheartedly.

    If you want to grow your project year after year sometimes you have to rewrite and adapt
    older modules to some new way you just have discovered. I learned it the hard way that if
    you do not understand your own code you can not adapt it. In this case it is much easier to
    rewrite a whole part of the project. And how often is old code considered a legacy or just bad ?

    And it is always the same story !

  3. elibenNo Gravatar Says:

    @Ron,

    When making an opinionated statement, it’s sometimes important to stick to absolutes and avoid political correctness. Otherwise it’s hard to make a point across. So sure, I could’ve peppered this post with dozens of “exceptions” and parentheses, and “unless”es, since I’m also a realist. I totally agree there are certain situations in which these “rules” don’t hold (as is true of all rules, including self-referentially). They do hold (IMHO of course) as a generalized statement.

  4. ripper234No Gravatar Says:

    I think this is highly dependent on the environment you’re working in, what expectations your managers have from you, and phase in product lifetime.

    In small startups, I think that 80% of the time you’ll be forced to make concessions.
    You try to make them small concessions, sometimes succeed, and sometimes fail.
    However, writing code that you’ll have a hard time understanding a year from now (if left unattended) is not an exceptional case at all in such an environment.

    There’s a saying I’ll paraphrase, I don’t remember the exact quote, but it goes something like:
    “If you come back to code you’ve written a year ago, and you don’t say ‘wtf, this code is bad’, then you haven’t learned anything in the last year”.

    This saying is of course also an exaggeration, but you get my drift.

  5. elibenNo Gravatar Says:

    @Ron,

    I totally agree with the “code from a year ago crap” quote, but it’s orthogonal to my point here. Even if your own code from years ago appears bad, it should still be easily comprehensible. And with regards to startups, I realize that I don’t have experience in such environments. I wrote code under tight deadlines, but even then I rarely deviated from my practices because you need to read code in order to debug it anyway, and over time this saves time, but YMMV.

  6. PhaniNo Gravatar Says:

    ‘I started my career as a software developer just a few months back. With all the new technologies and tools present, it is much easier to make clean and understandable code than a few years back. But still when I talk about code maintainability my peers laugh it off and politely ask me not to show off. The trend of getting immediate solutions to problems without any foresight to the future repercussions is very much prevalent and is passed down from one generation to another. If the boss condones shabby code then who will waste time in writing a clean and beautiful code.’

  7. MichielNo Gravatar Says:

    If you don’t take the time to read through your code and make sure its readable its more likely to be riddled with bugs anyway. The same “detached” review that you need to make sure others can read it is also your best protection against most serious logic flaws and dumb bugs.

    I’m busy with many start-up projects and even under deadline its always worthwhile to read through that code just one more time. Less time spent fixing bugs and explaining to others how the code and app works = more time writing new features!

  8. Oren EllenbogenNo Gravatar Says:

    I agree with the problem but not with the solution.
    People should be able to read their code, no matter how long ago it was written. It’s obviously a bad sign if you don’t have any comments to your “young self”.

    What I have troubles agreeing with is your solution. Just like writing a blog post, most chances it will be written to “void” (i.e not as many people will read it, at least not as you would hope for). Same goes about your product, most chances that your code will be used less often as you would hope for – your feature might be killed due to lack of usage, your product might change, your company might vanish etc.

    So, writing a “good” code, for me means:
    1. It’s easy to read it because it’s not trying to be over-sophisticated – using good names, sane comments, don’t try to write it in a “unicorn style”, trying to make yourself smile while others will cry.
    2. It solves a problem and nothing more. You can always come back and change it to solve one more problem, but trying to prevent every little edge-cases that 99.99% will never happen, will make your code a disaster to maintain.

    Going over your code again and again, will create a ceremony of perfection, which simply is not required and might do more harm than good. Just like writing a post – make it to the point, offer a solution and be smart about your time.

  9. FransNo Gravatar Says:

    A totally agree with this statement.
    Well said Eli !

  10. Rob GNo Gravatar Says:

    Related posts:

    Understanding the x64 code models
    understanding web programming & design with PHP / XML / XSLT

    Really? I don’t quite follow the relationship myself.

  11. CoderNo Gravatar Says:

    Whilst the sentiment is there, i feel this article is talking b0ll0x….
    rereading your code 20 times just so you ‘remember it’ in the future is rubbish. Wheres the time to do this? Are you supposed to reread all the code youve every written? what if you work on a multi user project, are you supposed to read all their code 20 times?…
    Why not suggest the best practices in writting code:
    –sensible naming conventions,
    –comments in the code,
    –single responsibility,
    –logical grouping of code,
    –good formatting,
    –and the list goes on…

    proper coding style should mean that you are able to read and quickly get the gist of any code you read, be it yours from a previous project or another developers from a project you dont even know….

  12. Ben JuniorNo Gravatar Says:

    There will be always exceptions to the rules, like, for example, sometimes to write a piece of code that can be really understandable, (specially algorithms) it may be necessary to brake it in several if’s to clearly explain the process from the begining. And it works great. Later on, when you have time to optimize the code, you realize that you can combine several if’s in only one, however, this will make the code difficult to understand. In my early years of development, I use to do the optimization. Today, in the age of the extremely fast and multi-core processors, I prefer to write code easier to understand.

  13. RickyNo Gravatar Says:

    I’ve worked as a contractor in all company types from startups to major corporations. Broom closets to private offices with a view. In all cases, I ensured that my code was readable and heavily commented. Many times that saved my behind when I had to look at complex code I wrote a couple of years before and had to understand it again.

    There is no excuse for writing code that isn’t understandable, even in a startup. In some areas (automobile, medical devices), that gets downright dangerous. As the head of the software department at a medical device manufacturer, I require all code to be well commented and understandable.

    You may not have time to refactor or improve. Just make your code readable and understandable. It WILL save you in the end.

    In my department, the saying goes, “If you come back to code you’ve written a year ago, and you DO say ‘wtf, this code is bad’, then you haven’t learned anything in the last year!”

  14. FredNo Gravatar Says:

    Thoroughly good advice. One needs to develop a code structure that reinforces simplicity and structure. Not only does this ensure faster coding, but it underlies good sense. Good readability helps to develop an archieve of goals and practice. There is no need to re-invent the wheel everytime one is faced with a new programming problem. Code that is readable can easily be adapted to changed circumstances and different applications. Make this a new year resolution. Thank you.

  15. BPDlkemeNo Gravatar Says:

    I was attracted to this article because recently I have spent a lot of time refactoring the code on my own website, and formatting that code. And it is only now that I realise why my lecturers in college were such sticklers for standards and formatting your code.

    The second thing is commenting code, why do people not comment code? I mean nearly every language (if not all) has some way to put comments into the code. I take rippers’ point though, with deadlines etc, the pressure to just get it done, can often outweigh the need to produce “beautiful” well-formatted code (with or without comments. I suppose this is where languages like Java which force you to include these things are probably better from that perspective.

    Anyway, I suppose it is just common sense, do it right the first time, and we may all save ourselves a lot of time in the future when it comes to changing, maintaining, or simply reading our own code!

  16. Bob StineNo Gravatar Says:

    I’ve been programming over 30 years, mostly in small companies, over 10 years in venture-funded start ups. And I agree completely with this article.

    Sure, sometimes to meet a deadline you have to go with code that pretty much works but is not pretty. But the time and resource crunch faced by start ups means that they have even less time to deal with mystery code than stodgy old enterprise shops.

    If you write a lot of hard to decipher crap to meet a deadline, God help you when it comes to the next deadline. There’s the notion of technical debt (explained here: http://c2.com/cgi/wiki?TechnicalDebt); if you let it pile up, it will ruin you.

  17. John StewienNo Gravatar Says:

    I’d like to contrast with the startup guy. I’m a contractor, often working on multiple contracts at once, and often working short jobs of say 6 weeks where I have to take in the whole spec, learn new technology, and deliver the product. Sometimes it feels like my whole life is a startup. I do good work and I get called back to build on my previous work, I need to be able to know where I was at by inspecting the code. Sometimes things get put on hold for a week, or I jump to another project for a week, being able to ramp at full speed on the week old code is critical. I could not survive if I couldn’t read the code I wrote a week ago.

  18. elibenNo Gravatar Says:

    @Rob G,

    Yeah, the “related posts” plugin of WordPress can be silly at times.

    @Coder,

    I don’t think you understood the post. I did not suggest to explicitly re-read the code 20 times to memorize it. Moreover, it was not my intention to repeat the contents of Code Complete or any other book of the sort.

  19. gggustafsonNo Gravatar Says:

    ripper234, I do not know your credentials but I have been a professional programmer for more than 42 years. I write these comments based on that experience.

    You are wrong! So wrong that I fear that your work would not meet my expectations as your team lead. Using discipline in writing software is a reflection of the discipline applied during its design. Additionally, imposing discipline during coding saves significant time when adapting earlier-written code for a new purpose. I learned this lesson in 1974, and it is one that has stayed with me ever since.

    Readability is a measure of the maturity of the developer. If you create your code in a disciplined way, even if the code is a “throw away”, you will develop the habits required to become a great programmer. Time constraints are an unacceptable excuse for sloppiness. It will cost far more when customers desire a change, since the change may trigger a total rewrite by someone other than you. Also, once you learn how to do it, producing readable code does not take any longer than writing unreadable code.

  20. FletcherNo Gravatar Says:

    I have to disagree with your statement: “Refactor fearlessly”. While this may be OK for development, it doesn’t work when modifying production code. The principle of “If it ain’t broke, don’t fix it!” applies with a vengeance because unintentional regressions in tested code can occur. The only justification for refactoring working tested code is to enable the implementation of fixes or new features. Refactoring is not justified for increasing beauty/readability.

    I’ve been professional software engineer since 1984 and a hardware engineer before that. I do have to strongly agree that code readability is paramount, but this should result from good programming practices coupled with judicious use of comments, especially when the consequences of a particular tract of code is not immediately obvious. Try micro-coding or real-time coding sometime to see what I mean.

  21. AshNo Gravatar Says:

    Writing code to me is like writing poetry. Sometimes I get the right inspiration and I may land up writing a beautiful 500 lines long very efficient sql query. I may even put some great comments. The very next day, I may look at the sql statement, and scratch my head. Here is the difference I have between Eli’s proud developer and me. I give benefit of the doubt to the inspired me of yesterday, and I say to myself that if I did it this way, I must have had a very good reason to do it. Let me try to figure it out.

    True sql geeks will understand where I am coming.

  22. JonoNo Gravatar Says:

    Oren Ellenbogen said: “trying to prevent every little edge-cases that 99.99% will never happen, will make your code a disaster to maintain.”

    As opposed to the actual disaster that occurs when your nuclear power plant control system hits one of those edge cases…

    :P

  23. Dan SuttonNo Gravatar Says:

    Of course, there is such a thing as putting comments in code. If you’re going to write something which is unreadable because it’s so tight that writing it more readably would slow it down (i.e. you’re writing something without making concessions to the programmer, simply for the sake of efficiency) then put a comment on it: not a difficult thing to do, and something which won’t affect the speed at runtime.

  24. PeterWoosterNo Gravatar Says:

    I’ve also been a professional programmer and developer for many years and sometimes I find that it’s actually quicker to write readable code rather than overly clever unreadable code.

    Recently I had a parsing problem that might be able to be solvable using a clever regex. The alternative was to use a simple regex that found the important tokens and then feed that through a simple finite state machine. This took more code but much less time to write than the complicated regex would have. It’s also much easier to prove correct, debug, read and modify.

    I used to work in APL and the writing of clever “one-liners” was a badge of honour to many junior programmers. It also resulted in unreadable code that took longer to write and often used far more memory and processing time than more straight forward solutions. The same culture is now seen in the regular expression world. PERL has been described as APL was as a write-only language.

  25. Ran DavisNo Gravatar Says:

    as the saying goes…. “There is never enough time to do it right, but always enough time to do it over” – make it readable and include working unit tests!

  26. Anonymous CowardNo Gravatar Says:

    I disagree with comments above stating that you occasionally have to write ugly code due to various constraints. There is not a single case ever when writing unreadable code makes sense. Especially at a startup, where code gets rewritten and changed at a much higher rate than in some stable and way less dynamic codebase, you get to change the code very often. It may look like you trade code quality for speedier deliveries, but you actually trade code quality for delayed deliveries. If code is unreadable, has no unit tests, is hackish or has whatever other problems, your overall effort will be larger and delivery will take longer. That’s not something most startups can afford.

    I also disagree on commenting code. Extremely rarely should you leave comments in code. The only situations worth commenting are awkward implementation details which cannot be understood any other way, like workarounds for compiler bugs, library bugs or external web service calls. Comments are not checked by the compiler, and thus become buggy very quickly. Maintaining comments is tedious and error prone, and cannot be automated. Comments make sense only when documenting library code from which you extract documentation a la Javadoc. In any other case I’ve seen comments just add cost, not value.

    Besides, there’s one more issue with comments: comments hide away problems in code. Code should be readable. If code isn’t readable, there’s a problem with that code – a problem which, if left behind, will add to the technical debt. Adding comments just hides the problem, it doesn’t solve it. Therefore, when you feel the need to comment, take a step back, find out what’s wrong with your code, and fix it. Chances are of five nines, IMO, that your need to add comments will go away.

    As for refactoring, I seldomly have any use for it after I’ve written a piece of code – because I start refactoring from the very first moment I write a piece of code. As such, it’s already clean and shiny in its first incarnation. Only if the context surrounding a piece of code changes fundamentally is there a need for refactoring it. I found that this also speeds up development. If you refactor as you write the first version of code, the resulting code is usually more compact, less complex and better testable. That leads to a significant economy of effort.

    Also, whenever I hear somebody talking about complex code I have to wonder. What is complex code? The only really complex things I have seen, in almost 15 years of professional programming, are encryption algorithms. If you have a complex problem, you split it into several smaller problems, which you solve in isolation. If you repeat the process long enough, you end up with code which isn’t complex anymore. The problem it solves might be complex, but the code implementing the solution shouldn’t be. Complex code is hard to test and to understand, and if the solution you’re implementing is complex, you don’t want to make it even harder to understand by providing a complex implementation.

  27. KenNo Gravatar Says:

    YES! Comment before you code! 1. Write WHY the code is needed. 2. Write HOW you are going to do it. THEN code.
    I don’t know how many times I’ve opened 10K lines of code in one routine with 150 GOTO statements sprinkled throughout. Logic where if “this” is true go here, do some work, if “this” is false go here, do some work. There’s labels sprinkled throughout so you have no idea if what looks like dead code really is, no matter how many times you read it.
    Some random ordering of labels is expected, but one time EVERY label was randomly organized, UGH.

    I don’t care how rushed this code is, do the top 2 things FIRST and ALWAYS. (You can skimp a bit on how, but go back and update it when how is changed.) “Do two miracles” does NOT count as how. You can start with what those miracles are and admitting you don’t have a clue at this time, but go back and update it when the clues arrive.

  28. gary knottNo Gravatar Says:

    Hear, Hear! – You might enjoy the parallel essay: http://www.civilized.com/programming.html

    - gary knott.

  29. Bruno LanevikNo Gravatar Says:

    I’ve been programming for a few years now. I may not have as much experience as the majority of those posting here. But reading this article made me come to realise something.

    As some of you are writing here that as a startup meeting a deadline is very important and it doesn’t matter if the code meets standard or not. This was the very reasoning that brought our company to it’s knees. We got mysterious bug after mysterious bug. Then a month after our launch we starting hearing from custommers that they couldn’t get through the payment portal.

    I was responsible for a different part of the project then the web application. So I wasn’t too blame for this. However this made me realise the importance of writing code that you fully understands. Because when you see a bug it doesn’t take you an hour to find it. It takes you 10 minute.

    The conclusion of my story is that sometimes you might save more money and time to push the deadline than to publish “nasty” code.

    Sorry for the structure of my post english is not my main language.

  30. Syed Nisar BukhariNo Gravatar Says:

    I fully agree with you…and this ia a nice article….what i feel is that code refactoring is important..small is beautiful…and the conventions like naming conventions for variables,functions,objects,comments are very important …and this is how ypu qualify to be a professional programmer……readability has a value….Hope everyone follows it

  31. DicklyDodgerNo Gravatar Says:

    It’s easy to talk the talk when you’re a backyard programmer dabbling in side projects. The truth is real developers write code in a limited time-frame. Later, optimization, something I’m sure you’re unfamiliar with, coming before “looking pretty” makes matters like readability even worse.

  32. Benjamin SmithNo Gravatar Says:

    Having managed a “start up” environment for over 10 years, in an organically growing company that has consistently grown about 70% per year, I’ve made it a point to focus on long term maintainability and readability almost above all else. Coding standards are almost religiously adhered to, down to variable names and standards for capitalization of code, indentation, etc.

    The result in a large, scalable, flexible, normalized, modular, easily refactored code base that spans numerous product suites while being tightly integrated. Code you can’t read is simply unforgivable.

  33. DartteemoNo Gravatar Says:

    I think, version control, pair programming, code review, naming convention could make it better

  34. Gordon EichmannNo Gravatar Says:

    I don’t find anything wrong with not being able to read code you wrote last week. It is pretty much the industry standard. It just means that you need to spend 20 minutes more getting zoned in before you commence work. There is nothing wrong with that.

    Folks who write readable code are in my experience lesser programmers than those who write ‘unreadable’ code. Of course unreadable is code for ‘stuff that is over the reader’s capabilities’

  35. elibenNo Gravatar Says:

    @DicklyDodger,

    Could you clarify what you mean by “backyard programmer dabbling in side projects”?

  36. Jason McCrearyNo Gravatar Says:

    If you’re interested in this topic and practical solutions, I recommend reading Implementation Patterns by Kent Beck. I’ve found my code far more readable since. Almost reaching the point where comments are unnecessary.

  37. Brice RichardNo Gravatar Says:

    Bullshit article….sorry I can’t agree with you. In my opinion, if you can understand every line of code you’ve written over a prolonged period of time, in my mind it means you aren’t writing challenging or even interesting code.

    I’ve been a developer for over 11 years and I can tell you that while my code is readable, it certainly doesn’t mean that going back to code I wrote say, 8 years ago would be easy for me to understand.

    First off, I’m a much BETTER developer now than I was then so who knows what practices I was using then? To the extent that I would be able to “understand” what I wrote, it would most likely be easier, instead of understanding it per se, to just REFACTOR it in a way that made sense for me CURRENTLY.

    I have to call BULLSHIT on this article. Sorry. I think it is arrogant to suggest that you can understand every line of code you’ve written over your lifetime and that if you can’t, someone you are damaged professionally in some way……b u l l s h i t.

  38. niknoxeNo Gravatar Says:

    My personal progamming mantra is ‘Code Right First’. From 100 lines of code I have written normally 100 lines are changed at a latter stage.
    This is nothing to worry about, just daily routine. Code evolves, code grows.

    As I have reworked my or others code that often, I can not overemphasize the main thesis: Write readable code! Do it right form the start. You will come back, sooner or later.
    Happy coding!

  39. SkippyNo Gravatar Says:

    To ripper234 :

    You say “Sometimes you just don’t have the time.”

    Sure … but does that contradict Eli when he says ?

    “not being able to understand the code you wrote a week ago, or a year ago, is unforgivable for a professional programmer” ?

    Is a Macdonald’s hamburger assembler or a pizza cooker a Cook ?
    Is a taxi driver a Pilot ?
    Is the person who writes articles in a “People” magazine about who went out with who a Writer ?

    None of them has time. As the French say, programmers working in the context you say “Pee code”.

    Eli is considering programming as an art. Like a string instrument maker. A shoes maker. A suit maker. The ones that take the time needed to build a product that they are Proud of.

    The sentence that caught my eyes was “Try to detach from your current stateful understanding of the problem”.

    A general statement, rarely expressed, but incredibly important…

  40. Anonymous CowardNo Gravatar Says:

    @Brice Richars: you say “Bullshit article … (…) if you can understand every line of code you’ve written over a prolonged period of time, in my mind it means you aren’t writing challenging or even interesting code.” Sorry, I’d say that’s BS, not the article.

    There’s a saying: good code is boring code. If you can’t make your code boring, there’s something to be said about your coding skills.

    Two programmers, both having a solid understanding and working knowledge of algorithms, data structures and design patterns, are likely to solve 99% of all programming problems they encounter the same way, and in a pretty boring and straightforward way, that is. If you’re not in this category, of course, you get to write “challenging code”. (Which is why programmers should IMO have a solid background in math, but that’s another discussion. I found a math head to be highly useful even if all you do is program CRMs. It helps you get your work done in a tenth the time a hard-working programmer writing “challenging code” needs, and you can go fishing for the rest of the day.)

  41. Charles MerrickNo Gravatar Says:

    Perhaps there should be a differentiation between throw-away code and code which is intended to be used. If you want to write throw-away code, it can be as ugly as you want. However, if somebody is actually paying you to do a task, you ought to consider that someone (perhaps your employer, perhaps a client) is expecting quality results from you. If you cannot deliver quality results, then perhaps you should go into another line of work.

    Clearly written code is important. You will read each line of code which you write perhaps fifty times. Others, if you are working on a team, will also read the code repeatedly. Of course, if your code is worthless, then perhaps it will not be read by so many others. However, it should not be your intent to write worthless code. If you value your own time, write clearly, so that you do not have to keep explaining yourself to those who are reading your code.

  42. dhunterNo Gravatar Says:

    My favorite quote is: “…refactor and improve fearlessly…”

    Love reading my old code, I get nostalgic, is like watching an old box full of my first toys when I was a child.

  43. John LockeNo Gravatar Says:

    There’s no excuse for writing shitty code. Not if you’re dabbling in backyard projects, not if you’re working for a startup. Especially if you’re working for a startup. You are not the only one who is going to be writing or maintaining your code. The developers who believe that writing sloppy, unmaintainable code is acceptable: I say laugh now, cry later. It makes me wonder if your ACTUAL code is ramshackle as well. Is that Ripper character supposed to be dressed like a ninja in his photo? Ok, whatever dude.

  44. Anonymous CowardNo Gravatar Says:

    @Charles Merrick: just fyi, there’s industry evidence (i.e. statistics done by ppl with a lot of spare time on their hands) that each written line of code gets read on average thousands of times, not just 50 times. That ought to give some perspective on how important it is to write readable code.

  45. YonyNo Gravatar Says:

    “Programs should be written for people to read, and only incidentally for machines to execute.” –Structure and Interpretation of Computer Programs by Abelson and Sussman

  46. anatoly techtonikNo Gravatar Says:

    It seems that with future evolution of Python and adding more stuff into it like async – the code will become unreadable no matter what. People have not found orthogonal language syntaxes yet.

  47. elibenNo Gravatar Says:

    @anatoly,

    I don’t see how async will make code unreadable. Programmers have been writing async code for years in many languages (Boost::asio, Node.js, Twisted, etc.). Standartizing one API and supporting it within the language can be a good thing here.

  48. DanaNo Gravatar Says:

    I totally agree! The code needs to be understandable. I do a lot of website redesign work and you wouldn’t believe some of the code I’ve come across. It’s sometimes impossible to understand what planet the programmers were even on when they wrote the code. It’s gibberish that takes hours to figure out.

  49. MasazNo Gravatar Says:

    I’m all for code readability but the first and foremost thing you have to do as a programer is to make the machine do what needs to be done. code readability helps with debugging and maintenance and upgrading .. but having a messy working solution is better than no solution … because you can rewrite it from schratch and in that time the software is still working.
    I’m not saying it’s ok to be messy. I’m saying that if constraints dont allow for it It’d better be working than be beautifull non working code. And when iI say constraints i say that the deadline is fixet not pushable….

    I must confess I tend to write messy code and i certinatly wouldn call myself a professional programmer althou i’ve been coding for 23 years (“professionaly” for about 15)
    I tend to plan out thourouly what to write in grand scheme detaiuls and rethink it multiple times (coleagues are joking that i’m charging for battle) then i can write readable well working code but recently i can only allow myself for it with big upgrades because then i have time for it. The demands now are so high and pace is so fast i sometimes write messy code like you said that even i after long time have to sit and read a few times to get it. But that’s my reality. I usualy have more time fr bugfixes and it happends that i have to rewrite something and it is spending more time on 1 thing than it would be if i wrote it properly the first time but then either i would write it or it would be dead in the water. This way it was working and then it became readable.

  50. DarrylNo Gravatar Says:

    Interesting comments around. Nobody has touched on this quote yet:

    “your code is your personal toolbox, one you will use and reuse over and over during your career”

    This is dangerous ground, in my opinion. Every line of code I write as a professional belongs to the company that paid me to write it. Only in very rare cases can you take code with you. (I’ve seen this when you write code while unemployed, bring it in and get written agreement that the code belongs to you. Most companies would prefer not even use it unless they can own it.) When you leave the employ of a company, taking a copy of the code can get you in serious hot water. (http://dealbook.nytimes.com/2011/03/18/ex-goldman-programmer-sentenced-to-8-years-for-theft-of-trading-code/?_r=0).

    It’s not code that I take from job to job, it is experience, and knowledge of how to do something. The knowledge belongs to me, but the code does not. If the knowledge is non-proprietary, I can re-use the knowledge, but without written permission, I’d never take or re-use even a line of code (that includes things like .bashrc and .emacs files — both things I’ve gotten written permission to take with me before). Can you comment a bit more on what you mean by your ‘personal toolbox’?

Leave a Reply

To post code with preserved formatting, enclose it in `backticks` (even multiple lines)