10. Comments explaining “what”, but not “why”

Introductory-level programming courses teach students to comment early and often. And while this may be a useful practice during programming infancy (when even the simplest line of code can be incomprehensible), many programmers never bother to shake the habit.

Do you have any idea what the code above does?

Me neither.

The problem is that while there are plenty of comments describing what the code is doing, there are none describing why it’s doing it. Now consider the same code with a different set of comments.

Much better! Even if we still don’t fully understand what’s going on, at least we have some much needed contextual information to go off of.

Write comments to help readers understand the code, not the syntax. It’s fair to assume that anyone reading your code has a basic understanding of how a for loop works. What they may not be aware of is why your code works or why you chose to implement it the way you did.

9. Interruptions

In general, programmers tend to be more akin to locomotives than ferraris; it may take us awhile to get started, but once we hit our stride we can get an impressive amount of work done. Unfortunately, it’s very difficult to hit your stride (also referred to as “being in the zone”) when your train of thought is being constantly derailed by clients and colleagues.

8. Scope creep

Wikipedia defines scope creep as “uncontrolled changes in a project’s scope”. Scope creep can turn a relatively simple request into a horribly complex and time consuming task. All it takes is a few seemingly innocuous keystrokes for scope creep to destroy a project’s timeline:

  1. Version 1: Show a map of the location
  2. Version 2: Show a 3D map of the location
  3. Version 3: Show a 3D map of the location that the user can fly through

7. Management that doesn’t understand programming

Compiling
Ok, so maybe there are some perks.

Management is not an easy job. People suck; we’re fickle and fragile and we’re all out for #1. Keeping a large group of us content and cohesive is a mountain of a task. However, that doesn’t mean that managers should be able to get away without having some basic understanding of what their subordinates are doing. When management cannot grasp the basic concepts of our jobs, we end up with scope creep, unrealistic deadlines, and general frustration on both sides of the table. This is a pretty common complaint amongst programmers and the source of a lot of angst (as well as one hilarious cartoon).

6. Documenting our applications

Let me preface this by saying that yes, I know that there are a lot of documentation-generating applications out there, but in my experience those are usually only good for generating API documentation for other programmers to read. If you are working with an application that normal everyday people are using, you’re going to have to write some documentation that the average layman can understand (e.g. how your application works, troubleshooting guides, etc.).

It’s not hard to see that this is something programmers dread doing. Take a quick look at all the open-source projects out there. What’s the one thing that all of them are constantly asking for help with? Documentation.

I think I can safely speak on behalf of all programmers everywhere when I say, “can’t someone else do it?“.

5. Applications without documentation

I never said that we weren’t hypocrites. Programmers are constantly asked to incorporate 3rd party libraries and applications into their work. In order to do that, we need documentation. Unfortunately, as mentioned in item 6, programmers hate writing documentation. No, the irony is not lost on us.

There is nothing more frustrating than trying to utilize a 3rd party library while having absolutely no fricken idea what half the functions in the API do. What’s the difference between poorlyNamedFunctionA() and poorlyButSimilarlyNamedFunctionB()? Do I need to perform a null check before accessing PropertyX? I guess I’ll just have to find out through trial and error! Ugh.

4. Hardware

Any programmer who has ever been called upon to debug a strange crash on the database server or why the RAID drives aren’t working properly knows that hardware problems are a pain. There seems to be a common misconception that since programmers work with computers, we must know how to fix them. Granted, this may be true for some programmers, but I reckon the vast majority of us don’t know or really care about what’s going on after the code gets translated into assembly. We just want the stuff to work like it’s supposed to so we can focus on higher level tasks.

3. Vagueness

“The website is broken”. “Feature X isn’t working properly”. Vague requests are a pain to deal with. It’s always surprising to me how exasperated non-programmers tend to get when they are asked to reproduce a problem for a programmer. They don’t seem to understand that “it’s broken, fix it!” is not enough information for us to work off of.

Software is (for the most part) deterministic. We like it that way. Humor us by letting us figure out which step of the process is broken instead of asking us to simply “fix it”.

2. Other programmers

Programmers don’t always get along with other programmers. Shocking, but true. This could easily be its own top 10 list, so I’m just going to list some of the common traits programmers have that annoy their fellow programmers and save going into detail for a separate post:

  • Being grumpy to the point of being hostile.
  • Failing to understand that there is a time to debate system architecture and a time to get things done.
  • Inability to communicate effectively and confusing terminology.
  • Failure to pull ones own weight.
  • Being apathetic towards the code base and project

And last, but not least, the number 1 thing that annoys programmers…

1. Their own code, 6 months later


Don’t sneeze, I think I see a bug.

Ever look back at some of your old code and grimace in pain? How stupid you were! How could you, who know so much now, have written that? Burn it! Burn it with fire!

Well, good news. You’re not alone.

The truth is, the programming world is one that is constantly changing. What we regard as a best practice today can be obsolete tomorrow. It’s simply not possible to write perfect code because the standards upon which our code is judged is evolving every day. It’s tough to cope with the fact that your work, as beautiful as it may be now, is probably going to be ridiculed later. It’s frustrating because no matter how much research we do into the latest and greatest tools, designs, frameworks, and best practices, there’s always the sense that what we’re truly after is slightly out of reach. For me, this is the most annoying thing about being a programmer. The fragility of what we do is necessary to facilitate improvement, but I can’t help feeling like I’m one of those sand-painting monks.

209 responses to Top 10 Things That Annoy Programmers

  1. Tom said:

    I’d agree with #1. I’ve written the same web app 3 times. Although I really didn’t know much the 1st time as I was new to it. But after reading some practice books, version 3 is great. Now just to see if I feel that same way in 6 months.

    • Eric said:

      I used to agree with #1 more so ten years ago than now and had a similar situation to yours. I had inherited a financial reporting site from a previous developer which he craftily written with content caching and what not but he problem was is that it didn’t scale whatsoever. When we started ramping up content it all locked for long periods while displaying. I did a massive overhaul which lasted great for the next year or so, but spoke with the owners directly and took the responsibility for a complete re-write.

      Added new functionality (necessary and wanted), plus minor aesthetic changes and ultimately the codebase was smaller, more efficient and scaled considerably well. That final version helped sell the startup and allowed us to move on to the next great thing.

  2. chris said:

    had to lol at #1. i dred those days when a 6 month old project (or older..) project comes back into the mix, I’d usually like to just write it from scratch! lol

  3. What about having to finish someone else’s work, or work with someone else’s code? Even if it’s well commented/documented, you can always find something that you would have done differently.

    • Guillermo said:

      “What about having to finish someone else’s work, or work with someone else’s code? ”

      Completely agree, I’d even put it on the 1st place.

    • FarmerHE said:

      Thats of the list… its a no go to do that

      Especially if its made by a idiot that shouldt be allowed to even start a computer… And only making documentation that says the excact same thing as the method name…

      Not to mention that Ive worked on fixing it for 4 months now…

    • LZEE said:

      what do you mean “even if it’s well commented/documented” ? It’s NEVER well commented/documented. If you have to work on it, other people’s code ALWAYS sucks, by definition.

  4. Dan said:

    Obviously not written by a corporate programmer. Its like the list was written by a student who doesn’t know big bussiness has had computers for more than 50 years. Medium business 500 million a year have had computers for 40 years. And your rewriting something thats six months old, you can’t communicate, don’t know how to stop scope creep.

    • Darren Stalder said:

      This is something with Corporate Programmers. It doesn’t matter than we solved many of these things 30 years ago. No one listens. The number of times I’ve wanted to beat managers to a pulp with a copy of the Mythical Man Month is a countable infinity.

      • peterchen said:

        “The number of times I’ve wanted to beat managers to a pulp with a copy of the Mythical Man Month is a countable infinity” –
        I think you are using it wrong ;-)

    • Gats said:

      Perhaps this comment was writted by a corporate programmer who’s bogged down in 40 year old process.. undoubtedly said corporation is now outsourcing to an agency that can get it done on budget and on time.

    • Jeff said:

      Ha ha – well done Dan, that’s the funniest thing on this page.

    • Izzy said:

      LOL thank you for demonstrating #2. You are that be-suspendered guy at IBM who smells like coffee and doughnut farts and was moved to the dungeon office in the basement by a manager 20 years your junior because the amount of functional code you produce is dwarfed by the amount of misery you cause your co-workers. Yeah, Dan, I know who you are. See you at work. Good luck finding your red swingline stapler.

    • Lukas said:

      Can’t communicate? Don’t know how to stop scope creep?
      I presume this corporate did not change any scope in the last 40 odd years and the programmers did not learn anything new in that period. Are they still around and working with 40 year old computors?
      We have a saying in our country roughly translated mean. Empty vat keep your tap closed. Maybe someone will think you hold something.
      I think the article is so true………

  5. Jake said:

    @ Dan

    Actually this feels like it was written by a corporate programmer since these are things that annoy corporate programmers.

  6. Kevin Pang said:

    @Dan

    Jake’s right. I am a corporate programmer. I’m not sure whether I should take offense at your comment because I’m not entirely sure I understand it.

    Would you care to elaborate on how big businesses and the length of time they’ve had access to computers relates to this article?

  7. Bryan said:

    Wow, great list. I can wholeheartedly agree with everything on the list. I suppose order will differ for everyone. Feature creep and hard to get along with "other programmers" would be my number 1 and 2 things.

  8. Mickey Phoenix said:

    You seem to have omitted one of my pet peeves: "Off-topic and bizarrely ungrammatical comments made by people with nothing to say, who adopt a disgruntled pose in an attempt to appear experienced, but who merely succeed in making themselves look humorless and confused."

    Fortunately, Dan obliged us with a perfect example, thus rectifying your omission.

    • ProgrammerMan said:

      Mickey leave Dan alone, he’s simply suffering from a severe case of “Rectal Cranial Inversion”. It’s quite a common affliction you know, only known cure is to accquire a open mind.

  9. Sara said:

    Good List … @Kevin – start up developers don’t run into these type issues often as we govern over our code like it’s our child, and everytime something new is checked in it is usually examined by the whole team. So, even in six months we are all still horribly proud of our contributions (USUALLY)

    Also, we’re a little more into Self-Documenting Code :)

  10. Chickenshit said:

    Woahh, did enjoy this one… ;-)

  11. Chris Love said:

    Amen!!!! Great list, I think I will post it and carry it with me always.

  12. Les said:

    I think Dan’s point is that companies have known about these issues for 40+ years and worked around them.

    Becoming familiar with the hardware is important. Recently an annoying fact has been the capacitor meltdown of power supplies manufactured recently.

    http://en.wikipedia.org/wiki/Capacitor_plague

    SECDED for memory (ecc) is another hardware topic. Perhaps code should be written defensively to recover from some memory errors. I picked out a consumer (non-server) asus motherboard recently and it was difficult to find a model that had secded, which is an unfortunate sign.

    http://cr.yp.to/hardware/ecc.html

    Finally, for the other programmers category it sounds like they aren’t very good. Perhaps peoples abilities hover at some set range for a while, with each programmer working at different level of an exponential scale. If you’re too many levels away there could still be learning both ways but at some point there will be friction and less productivity.

    The train example is ok except it doesn’t explain how someone can stop the momentum of a train in a split moment with their interruption, perhaps even reverses its direction and driving it off track into a funk. I like the house of cards example of keeping things loaded in your mind. Its easy for someone to topple that. Perhaps this suggests we need to do mental exercises to a far greater level, akin to the movie Pumping Iron for weight lifting, in order to weather the (corporate) storm.

  13. Luke said:

    Haha, nice one Mickey. I was kinda thinking the same thing but didn’t know how to put it into words. Great list!

  14. T said:

    outstanding!

  15. Right on. I would have put #10 at #1 though. I see and do this so much. We get so heads down focusing on what we are doing that we often forget WHY we are doing it. Writing WHY comments also helps you keep on task…cause you know…sometimes your solving a problem that doesn’t absolutely need solving right now.

    • Jan Goh said:

      Fully FOUR of these problems go away with good commenting: #10, #6, #5 and #1.

      #10 should be obvious. #6 and #5 are mitigated because if you comment as you go, not only are you solving #5 for someone down the road, you can pull relevant information about features right out of your code headers. Most of the user documentation should be done before things are started anyway; someone should have given you a design document to start with. Assuming the design document was something worth adhering to, it makes a good basis for user docs. If it wasn’t worth adhering to, well, you should have been documenting your decisions along the way so that you don’t catch hell later anyway.

      And when your comments are good and readable, you find yourself less irritated at the mistakes you made because at least you remember their justifications. When you find old code (and can change it), you simply update the code, update the justifications, and walk away happy that you were able to apply your experience to a problem. You can see real progression.

      The only time I’ve been particularly unhappy with my code is when I went back and discovered that I got lazy, so I had to spend time unravelling the stuff that I wrote. What a waste of time! When my comments were good, I went in, changed exactly what I needed to and how I needed to and got back out.

      • Aboo said:

        “Most of the user documentation should be done before things are started anyway; someone should have given you a design document to start with.”

        LOL – That’s funny. You sound exactly like one of our new programmers, fresh out of university. NOT saying you are, just so… optimistic!

        A.) Design documents are never complete. Refer to the list again to see problems caused by this.
        B.) Finding two programmers, on the same team, that write similar constructive comments is a bloody miracle.
        C.) Finding a documentation tool that can create useful docs for anyone but the developer that wrote the code to begin with is a miracle of near “virgin birth” proportions.

        15yrs – from start-ups to huge corps. All of these problems exist to varying degrees. The only folks who deny that are middle-managers, during meetings with clients or upper management.

      • AJ said:

        Most of the user documentation should be done before things are started anyway…

        PLEASE let me live in your world!

  16. Saulo said:

    Hey Kevin,

    I am not a corporate programmer, I’m still an undergrad, (hopefully graduating next Spring) but I’ve had Summer jobs where I had to work with other developers and yes, I can relate with most–if not all–of points you mentioned above! Thanks for the good read!

  17. bayuadji said:

    Woaaah, nice list
    couldn’t agree more especially no #1

    "who write that stupid code? hmm let me see the subversion, oopps it’s me" :P

    • Simon said:

      Oh, yeah – I’ve done that many a time. Grumbled about “what moron wrote this crap”, and yes, sure enough, it was me about five years earlier…

      Though, personally, I like going back to my old code. It’s easy to look at other people’s bad code and feel superior. But when it’s your code, it’s a humbling reminder that five years ago, you thought that code was a masterpiece..

      • James said:

        I’ve even had a few projects I’ve re-written (re-programmed, or re-worked) after the fact, just to make it better and to bring up-to-date with my recent experiences.

        Things tend to be easier when you’ve had time to think and dwell on the issues and solve them again. Usually the first time, your in too much of a rush to get the project done on time (which is never enough)… and get caught up in the push for release.

  18. Excellent list. #1 had me grinning from ear to ear as it’s oh so true.

  19. Kevin Pang said:

    Thanks for all the kind words everyone! :-) Glad you all enjoyed the article. I have to admit that it was quite cathartic to write it all out.

  20. Tim said:

    Agree with all. Some much more hilarious than others, but perhaps that is because I still feel the pain.

    20 years of experience in the business negates absolutely *none* of this list. And 20 years from now – it will be just as relevantly funny.

    A Little like someone taking your chest hairs and pulling them all out at once… (Sorry, not a woman, so can’t make a relevant analogy… although there is waxing I suppose…)

  21. Jon Limjap said:

    Kevin,

    LOL, so this is the outcome of your question in stackoverflow? :) Great article summarizing it though!

  22. CodeMonkey said:

    I think it’s a shame when somebody takes all the effort to name symbols and lay out the code properly and then does not document it, living instead under the arrogant assumption that, since the code is so well written, his collegues will instantly understand how the code works.

    If you’re writing only for the compiler, please don’t bother with indentation, newlines and proper variable names… That way I won’t bother with reading your code either!

  23. chang said:

    You know what? Fuck you.
    I can’t take you seriously because .Net is a fucking joke and so are you.

    • Martin said:

      Chang – you’re the joke. Obviously you’re incapable of real world programming and probably cannot master .NET and therefore feel inadequate. It intimidates you because you cannot grasp it and that makes you feel small and inferior.

      You probably think that javascript is a real programming language and still struggle with HTML.

      The unfortunate thing is – is that you probably can’t program at all and don’t have any real-world experience. When you eventually grow up, you’ll see the light. Until then try to at least show some maturity.

      • Sam said:

        But Javascript *is* a real programming language!

        • Alexander Kellett said:

          As in .NET. Alas most practitioners barely now 1.0 never mind 4.0 of C#.

  24. Jon Limjap said:

    LOL @chang

    And that is why my answer in this stackoverflow question is that I am annoyed at zealots who just ruin everything.

  25. Stephan said:

    I prefer no comments but a method in this case:

    squareRootWithNewtonRaphson(int n)

    and another abstracting the implementation away

    squareRoot(int n) {
    return squareRootWithNewtonRaphson(n)
    }

    Peace
    -stephan

  26. Frank said:

    Great list, but in number 7 you forgot to give credit to the xkcd strip you showed:

    http://xkcd.com/303/

  27. aespe said:

    cool.. so me!
    hahaha

  28. based on my recent talks on SEO and feedback at barcamp, id have thought that the #1 thing (web) programmers hate is SEO!

    poor me

  29. Bob said:

    We have to accept that we will never know it all and that perfect code is a pipe dream.

    What are you? Absolutely nuts?

  30. hacker said:

    Being apathetic to the code base and project is the most annoying thing according I find at work.

  31. Pop Catalon said:

    You should add to the list: working with any Office products, Excel, Word, or other stuff a "real" programmer shouldn’t touch … ever.

    • Jamie said:

      Haha! Spoken like the most annoying kind of programmer — the kind that refuses to accept that people who are *not* programmers actually use those tools all the time, and they serve a purpose, so dealing with them is part of your job.

      I’d rather write a macro to do something for a non-programmer in word, or import/export from excel, or whatever, if it means that overall, the job gets done faster and more efficiently. Maybe it’s “better” to write a whole application to do whatever it is that’s being done in excel and not have to use it at all, but why write code to do something that can be done well enough with excel? Why reinvent the wheel?

      That’s one of my biggest pet peeves with some programmers: the principled refusal to accept that the “best” way to do something isn’t always the most cost effective or reasonable to get a job done given your available human resources. A lot more people can do stuff in excel than write code, so why not basically use Excel as a user interface for some situations when its appropriate.

      • Sam said:

        I think he meant he hates *using* them.

        My biggest issues are with Word (so far):

        1. I always get very frustrated with Word’s lack of support for floats — why can’t *it* find places to stick my tables and figures? TeX has been able to manage this for about as long as I’ve been alive…

        2. Next to nobody knows about the “styles” feature, which is probably related to its’ not being terribly well documented. This feature is a bit like CSS, in that it is allows you to separate content from formatting — which makes it a heck of a lot easier to change the font, text sizes, or line spacing later on without messing lots of stuff up: you just change it in a few “styles”, rather than in every differently-formatted piece of text like I can remember having to do in MS Works.

        I honestly think the main reason this feature even exists in Word is that MS’s own programmers could not stand to use Word for their technical documentation without it.

  32. alistair said:

    BTW, in Stackoverflow Podcast 19, the private beta will be finished on September 3rd, so the link will work after that (except it won’t have beta in the url?)

  33. Wayno said:

    An IT director briefed us that you should look at your own code three years from now, and be embarrassed; if not, then you haven’t grown as a developer.

  34. #9 is true and it also applies to me.

  35. Greg said:

    I think you missed a big one:

    When other people take credit for your code and/or take credit for your ideas.

    • Sam said:

      Does the former happen when using a decent VCS?

  36. David Castro said:

    Well, I guess based on #5 I’m quite the anomaly. I’m a technical writer (with a tech writing degree from SFSU) who loves to pretend I’m a programmer. I plan to go back to school for a Master’s in Comp Sci, and my dream job title is "Programmer/Writer" or "Writer/Programmer." Oddly enough, you don’t see that title very often! LOL!

  37. Zoodle said:

    Shouldn’t a top-ten list from a programmer start at 9 and count down to 0?

    I really enjoyed this list, and could relate to all of them. #6 is my downfall (especially when #1 happens!)

    • Richard said:

      Actually, it should start at 1001 and count down to 0000. Of course, I suppose it depends on the language you’re programming in – some use 0-based indices and some use 1-based.

      Or, the top 10 reasons could be 1 and 0, or 7, 6, 5, 4, 3, 2, 1, 0….

      Then again, perhaps I’ve had too much coffee.

  38. tr6 said:

    Great list, fully agree to all 10 things :)

  39. Reavenk said:

    Instead of reading your old code and saying "What the hell was I thinking?", what about those cases where you read someone elses old code and ask "What the hell was this idiot thinking!?" and an hour later into the code you remember you’re the one who wrote that file.

  40. Joe Holst said:

    Brilliant list, thanks for spreading the word.

  41. JeezLuis said:

    Ugh. What annoys me the most, to no end, is whining programmers complaining about everything there is to complain about.

    Instead of writing meaningless lists that annoy you (but cleverly enough projected upon all programmers), you should be proactive and "fix" those things that annoy you.

    You can’t understand what a piece of code does? doggone it, use your analytical skills and find out what it does.

    Losing your mind you’re getting interrupted so often? What about asking and/or telling people you need to focus on what you’re doing? Oh but I guess that would require some social skills.

    Scope creep? What about talking to stakeholders and explaining the HUGE difference wording can make? What about telling your manager than the ETA given initially was given under certain assumptions and these no longer hold true and thus you need to revise the estimate?

    And so on and so forth. Too doggone easy to complain, complain, complain. Avoid VCs and start-ups. With that complaining, whining attitude you won’t have a good time.

    • dawgbone said:

      Yeah, it’s great to use analytical skills to find out what it does, but what could take hours to do it that way (especially if someone nests functions and methods within each other) handy documentation cuts that work in half. So while it may take you as the developer an extra 20 minutes to efficiently document your work you could be saving several colleagues hours later on. Just seems too much like efficiency.

      And I’m not sure where you work, but sometimes you are in a situation where you are more than just a programmer and other things need to deal with. At work not only am I the Lead Web Developer I’m also the only one in the company who can handle the many tech support issues that come up. I also get paid for this aspect of my job and it as just as important as the Web Developer part. Doesn’t mean that when I’m in the zone writing code that an emergency tech support request doesn’t throw me off and annoy me.

      What you seem not to grasp is that sometimes you can explain issues to people hundreds of times but it doesn’t click. One of the V.P.’s at our company comes across issues on our site and sends an email that simply says “I got an error”. Obviously that tells me nothing, so I then have to spend time out of my day to go and talk with him to find out what he did so I can duplicate the error. Sometimes I get this email late on a Friday and then play email tag trying to sort the issue, or sometimes I don’t see the email until late and he’s gone to bed. So instead of being able to fix the issue right then and there, it waits until the morning. This has happened about 30 times in 3 years I have been here and every single time I’ve told him that you need to tell us what you did to get that error and it still doesn’t happen.

      All your suggestions are wonderful, but they just aren’t very practical.

  42. David said:

    I’m annoyed at having to work in front of an probably five-year-old 17" screen, while having a dual-screen setup (24" and 19") at home.

  43. Practicality said:

    @JeezLuis

    I think ironically the skills you are saying he should develop is the ability to complain. Just in this case, to managers.

  44. It is also recommended that if you write comments that explain "how", they are also correct.

    You write [quote]// square root of n with Newton-Raphson approximation[/quote], but it is not a Newton-Raphson method…

    • Richard said:

      Ok, but perhaps that was the point – the comments said that the intent was to use Newton-Raphson approximation, so obviously the original programmer didn’t understand the math he was implementing and you now have a clear bug to fix. Simply describing that r = n/2 means r equals n divided by 2 in your comments is retarded at best. With the “better” method we see what the intent was and can act on that information.

      Explaining how you’re doing what you’re doing is helpful if you’re describing the process, not if you’re simply restating the coded statement. “Iterate over customer records” is not helpful, while “iterate over customer records to find outstanding late charges” is something we can work with. It tells us what you’re doing and why.

      This is all very obvious. I wonder how many people are being deliberately obtuse….

  45. Paris Holley said:

    #9, that is the worst for me…I am very workflow oriented, and when im in the zone and on a roll, and someone comes over to bother me…it just kills my whole vibe..

  46. Bismark said:

    #1 never happened to me; only the opposite. I go back months later and think "did I really write this? guess I really am a genius."

    • Samuel said:

      I guess that means that your actually regressing in your ability to write code.

  47. jmc said:

    @JeezLuis

    Hypocrisy intended?

  48. LarryA said:

    Ahh yes, those days when you look at your code from a year or more ago and say, "wow was I really on the ball during that project!" I enjoy those moments and also think I may be slipping as I haven’t written anything so cool lately. :-)

  49. <b>Top 10 Things That Annoy CRAPPY Programmers</b>

    That would be accurate. High bandwidth developers have no issue with any of the above for except when it is severe and inappropriate beyond normal expectation for extended periods.

    Programmers with a clue know how to fix most of these issues with design, common sense, an understanding of organizational cultural and being able to view the world from other’s minds.

    Autistic people cannot do the last item, and many believe there is a tie between autism and programming/techniacal types. I believe there is as I see a fundamental lack of ‘empathy’ in many cases.

    It was burned into me after 2 decades of trying to make others fit my world. It never works and the ‘others’ involved will likely never change.

  50. AsakuraYoh said:

    So true…. I 100% agree with all that!

  51. Andy Bailey said:

    they’re all things that make me cringe because I’ve been guilty of it all!

    how about, not saving test files with the name "test.php" to see if it works? I must have a million different test1.php, testparse.php etc in my code folder and I have to open them up to see what they do (and mostly they don’t have a decent comment description either!)

  52. Kevin Pang said:

    @Damon Wilder Carr

    I disagree. "Crappy" programmers are ones that don’t care or know enough to be phased by any of the items on this list.

    You can make the argument that a good programming team won’t have as many of these problems surface, and I would agree. But the point still stands that these items are annoying, even if they occur less frequently. In the end though, you have to realize that not everyone is lucky enough to have an ideal working environment.

  53. binarywolf said:

    #6 is so true. Programmers should get to know one or two good tech writers.

  54. Jonathan Allen said:

    Showing an XKCD cartoon and linking to Dilbert? Not cool.

  55. Kevin Pang said:

    @Jonathan Allen

    Oops. You’re totally right. I completely missed the link to xkcd for that gem of a strip. Fixed now.

  56. Guna said:

    I am really surprised that so many of you responded to this list of "classical" issues so quickly…. I was reading through it (forwarded by my friend) thinking that it was an age old post !!!

  57. sikanrong said:

    #1!!! The truth!!

  58. SicTim said:

    I liked the documentation comment, although I approach it from the opposite angle — I’m a freelance writer and light editor who sucks at programming.

    It’s frustrating for me, as an end user, when I see poorly written or disorganized documentation. There are a lot of journeyman English majors out there who could use the work, or even just the resume padding. Technical writing is a nice, narrow field to have experience in. (Like, say, speech writing or comedy — my chosen fields. I’m not personally begging for work here.)

    If there’s really a demand in the open source community for people who are willing and able to write clear, concise documentation, I could see a symbiotic relationship with all the fresh faces out there who have both communication and geek skills. Some are just learning that they’re not going to be writing million-dollar screenplays or bestselling novels, and would embrace a way of catching a break and adding a marketable skill to their options.

  59. blpgirl said:

    I have to totally agree with you in most of this ;D.

    The interruptions cuz everytime i finally get completely into my program and coding i do so much work in an instance but if people interrupt me constantly i just waste my time o.O

    Ugh and documenting… man! that´s hard job :P i just procrastinate and procrastinate until i have no other choice but to write it and the worst of it is that i know it is important to do it.

    Hahaha! yeah and the application without documantation are so irritating, it takes you hours to figure out how to do something XD

    And the hardware… that´s so common is not funny, everytime some computer gets damaged at my house, they all say im the one who has to fix it :O

    Wahahaha and yeah my own code some time later!!! I just almost fall off of my chair laughing, totally agreed is the #1 most annoying thing. You just look at the code and wonder, what the hell was this person doing!? just to realize it was yourself who wrote it XD XD XD

  60. Kristen said:

    I’d like to know where Damon Wilder Carr works and see the perfect software it is that he works on.

  61. Good post :) It is extremely frustrating being interupted while being in a code mode, that can ruin the rest of the day for me :P

  62. Ryan Farley said:

    Great article Kevin. Just love the comments from the "everyone is stupid but me" idiots. Hehe.

    -Ryan

  63. Thogek said:

    I can agree with every one of these. Different programmers/engineers may place them in a different order (depending on experience), but I’ve seen every one of these, many a time, in large companies and small alike.

    Thanks for the dark laugh, Kevin.

  64. R said:

    Nice.

    BTW, it’s spelled "hypocrite".

    -r

  65. Kevin Pang said:

    @Ryan Farley

    Haha. Indeed. When my wife read some of the more obnoxious comments her response was "god, programmers are such whiny bitches". Truer words have never been spoken. :-)

    @R

    Thanks. Fixed now.

  66. DoomRater said:

    SicTim’s got a strangely awesome point. Over at the ZDoom Community we have a Wiki for documentation because a. Randy Heit doesn’t have time to maintain documentation and b. there are so many unofficial versions that it would be impossible to nail them all otherwise. Not only that, though- by allowing members of the community to keep the documentation up to date, scripters like myself have what’s in and what’s working available at our fingertips. It actually minimizes points 5 and 6 very well. I think it works great for the reasons SicTim said, too- we have a mix of geek writers and geek programmers.

  67. ZagNut said:

    Re: Dan’s comment on 8/28:

    You are a PRIMARY example of #2 (both on this post and you-know-what). One of the worst types of programmers to deal with are the ones with HUGE egos. They also typically tend to be no where near as good as they think they are.

    This is also epitomized in Damon Wilder Carr’s last line of his comment. I would never want to be in his "team".

    Good post, Kevin…

  68. Jayx said:

    Hi Kevin

    I found this via muti – great post. I am not a programmer, but I think this applies to other industries as well … I constantly get similar/same issues when doing design work and/or websites.

    Feed added :)

  69. Jon Cage said:

    Classic!

    "Unfortunately, it’s very hard to get into a programming zone when your train of thought is constantly being derailed by clients, managemers, and fellow programmers."

    managemers? ;-)

  70. Kevin Pang said:

    @Jon Cage

    The built-in spell checking that *most* applications offer nowadays has spoiled me rotten. Thanks for the catch. :-)

  71. aardvark said:

    I once saw a 50-page program, with 1 comment on page 25, which read: "they said I had to comment this program".

  72. Dana said:

    Loved the list! I think my personal number ONE would be Legacy code with counter-intuitive variable and method names. I’ve actually had to support apps I’d never seen before that were constructed in such a way that the methods were "cmd2, cmd1, cmd3" and variables with nonsense rpefixing like "sx_Process, IAB_Make" etc. I mean seriously – what the helllll… :)

    And yes, we programmers ARE a bunch of whiny bitches :) That made me smile most of all – your wife is a smart chick!

  73. McArthur Leger said:

    This list rules!! It should stay like that, And I would talk about less than 6 months, 2 weeks later are enough.. Even more, Don`t know guys, but there’s times when you write a code, you sleep, and when you see the code again, you don’t know what it does, or why you did it, or whatever..
    But any way, nice list!!

  74. sumesh said:

    Its just awesome…and when i look back……..eeeek i was like this….and still now :)

  75. drewbeta said:

    I used to work with another programmer who would explain the emotional reasons why he would do different things in the comments. It made for good reading. It would go something like:

    //it’s now 4 in the morning and I am gradually slipping into insanity. I smoked 4 cigs in an attempt to figure out why my iterations are escaping prematurely.
    //using this function to manipulate the global government. I know that I shouldn’t do it this way, but damn the man!

    I used to love reading his comments because the crazier they got, the closer he was getting to quitting again. I then knew when I was about to be handed more work.

  76. 1ac0 said:

    Howg.

  77. abc.def said:

    [b] AGREE [/b] – [i]#7[/i] – [u][/u]- [quote][/quote]

  78. Eneza said:

    under the MANAGEMENT that don’t understand programming is STUPID CLIENT REQUEST THAT DO NOT KNOW WHAT ARE THEY REQUESTING!!!!!

    Stupid CLIENTS! They just like moving objects even it is not suitable for the website!

    Make POWERPOINT INSTEAD!!!!

  79. Interrobang said:

    As a technical writer, I have to say that one of the things that makes me cranky is management that makes its programmers write the documentation. It winds up either not getting done or sucking and making the programmmers annoyed. I actually <i>like</i> writing documentation.

    I guess the way to approach the problem to management is to tell them that the programmers don’t have time, good documentation will cut down on support contacts, and it’ll keep the dev team happier. Everybody wins.

  80. LostInTranslation said:

    I may have missed it, but did anyone add stupid salesmen to this list. You know the guy/gal who promises the customer A,B, and C when you have only built A. When you tell them you only have A then they run to senior management about how the IT group let them down.

    I hate them.

  81. stratosg said:

    so true all of them… especially the 10th one is the one i do to my self (apply the first one and you got me :D )

  82. harry said:

    I agree with the last one :P

  83. Anthony said:

    I love lists like this because they are so reaffirming… While I agree with all of them, #9 is my cross to bear that I cannot get anyone to understand. When I get in the "zone" you can light fireworks in my hair and it won’t knock me off the pace. The trouble is getting [i]in[/i] the zone.

  84. Schahryar said:

    Nice list, thank you!

  85. Fattman said:

    Great list. Number 1 deserves its spot as (a) all good programmers have been there and (b) it reminds us that a little humility is no bad thing!

  86. tommy said:

    <b>#11. The management always wants the new project written in a new/different language… </b>(And we all know those "Learn #$%@# in 7 days" books are worthless.) :-)=

  87. natalie said:

    @drewbeta, that made me laugh so hard!! I think I’m going to start doing that myself.

    When I really get in the zone (#9), it’s hard to pull me out of it that quick. Especially if I’m at home. The husband will be trying to get my attention or have a conversation, and it’s tunnel vision for me – to the point that I don’t even realize he’s trying to communicate. By the time I do realize, he’s pissed off because I’m "ignoring" him.

    • Michelle T said:

      @natalie

      I am right there with you on this…my poor hubby and kids think I have fallen into the computer occasionally. But that is why I work at home, I can zone them out. I’m not so good at zoning out co-workers. LOL. I can live and breath code for hours and forget everything here in my office.

  88. Catz said:

    I agree with pretty much everything said above, but I would add; your boss saying ‘Ok people, let’s think out of the box on this one’. I’ve had a bad experience. Can you tell?

  89. Mark said:

    re: Vagueness

    My own bug bear here is where programmers expect the user to describe the problem in a manner that they can work from. For the love of Pete – you need to ask questions to get the information you need. If I [b]ever[/b] hear a programmer telling me that the user does not understand or they did not give enough information or that it was [i]their (the users)
    [/i] fault then my first thought is "what questions did you ask?". This is hopelessly generalised and I know that but I find that very often, the programmer did not really bother to ask questions … it seems it is much easier to blame the user.

    Apologies to all the coders out there who do take the time to question and help the people they write code for (and o all the others: you ain’t writing the code for yourself – you need them [i]users[/i] whether you like it or not).

  90. All,

    My simple points were meant to incite a reaction. If you were angry good! Now help be part of the solution.

    1) These issues are not going away and in fact they can be said to define the conditions of what a software engineer experiences.

    2) It is not the responsibility of others to change behavior it is our responsibility to help them understand what we need to be effective at our craft

    3) I used ‘crappy’ to get people awake. It’s good to be mad as most need to be shaken out of a comfort zone of ‘complaining’ about these items and actually ‘acting’ to fix them

    4) What most find is the best you can do is stop trying to ‘change others’ and instead change yourself (this is the bottom line here)

    Once you accept (4) only then will you often see change come from others.

    Believe me, I am not in any kind of perfect laboratory. I have the same issues as everyone, I’m just saying nothing from hard won experience little will change for you personally until you consider change from within.

    There is nothing demanding others to meet us on our terms, so the alternatives are quite obvious.

    Damon

  91. Gilbert said:

    Great list. All so true.

  92. Lisa said:

    Absolutely true!
    I hate reading my own codes after several months :D

  93. Ricko said:

    OMG, this is funny and sad at the same time.I agree with everything, but #1 blows me away.It’s totally true.And like someone said in another comment, working after someone else gives you headaches,and you start wondering if you save more time doing it again yourself.

  94. Tester said:

    http://www.library-book.co.cc << Free Download IT Programmer Java Linux ASP Flash PHP and much more Books

  95. Topchiyev said:

    Oh sorry, Kevin. I just started blogging so I just dont know some basic blogging ethics. I’ll note this. Thanks.

  96. Agustin said:

    for me the worst… scope creep!!!
    when I see old code I get nostalgic…

  97. Mark said:

    and finding you own code not found on corporate code repository, lol

  98. Fauxhawk said:

    Need to add one more: People/Clients Who think they know programming…

  99. fauxhawk is right, a lot of client think that they know programming and sometimes they want you to work with impossibles or no solutions.

  100. Fanamation said:

    Out of the Ten points middle 3 points really annoy me a lot,Could we overcome these?

  101. Canberk said:

    i really liked it. a great list. every coders have to reconsider about those bad inhabits and facilities objectively on his/her mind…
    Thanks for the post

  102. Kabon said:

    Ya it is really frustrating when we try to learn some thing then in a second there are available new thing that we should learn.

    Documenting is also the important thing but for people like me, it is really make me wired. Time is always kill me when i want to creating a documentation.

    One question for you, why did you explain it with 10 to 1 :D. Creative

  103. zeolite said:

    and the 11th are the top ten lists….

  104. yoshi said:

    AGREE #4

  105. I’ve encountered a lot programmer like that and it is really annoying specially if you will take over the project.

  106. Nice post..I see and do this so much. We get so heads down focusing on what we are doing that we often forget WHY we are doing it. Writing WHY comments also helps you keep on task…cause you know…sometimes your solving a problem that doesn’t absolutely need solving right now.

  107. Leroux said:

    Good post ! Bookmarked to show to some friends !

  108. dushy said:

    > 4. Hardware

    Iam a sysad – and i despise programmers who don’t understand the hardware and code high level crap!

    No sane company/process would ask a high-level programmer (as you say) to fix hardware issues. Its not a programmers annoyance to be in the list!!

  109. Mark Bell said:

    Excellent post—Nos. 9, 8, 3 and 1 are definitely my top annoyances…

  110. I couldn’t agree more with this article and it made me crack up thinking back to my own code I wrote years ago. Then you stare at it and go “oh, wth was I thinking?”

    In my own applications I use a LOT of API’s. Everything from bit.ly, weather channel, SEOMoz, and many others. What I found is that #5 is dead on. The documentation often times is lacking (if there at all) and I have to try and figure out how to make it work. That’s why I created The Easy API it started as a personal project to give me one easily accessible API that can interface other API’s. Once a few programmer friends of mine asked me about it I opened it to others. Now I’m adding in other API’s and am always up for suggestions.

  111. Mithun said:

    A great List.. :)

  112. Ken said:

    hehe, it seams to be a nice and funny article though. Bookmarked for reading later on :)

  113. thats a nice post. i really enjoyed the #7, as i know a little bit or nothing on programming most of the time the programmers try to dump us. :)

  114. Simon said:

    You know, it’s amazing how many of those ten things could be satisfactorily resolved with the use of a taser… I mean, some of them are fair, unavoidable issues – documentation has to be written, other people have to be worked with, and sooner or later you’re going to have to go back to the mess you made a few years earlier…

    Things like management, though, or scope creep or interruptions… those can be discouraged… :)

  115. John Brown said:

    11. No documentation that gives the “big picture”

    API documentation is necessary and code comments are good but if you don’t have a clear view of the architecture, main design elements and flows (sequence diagrams anyone?) through the system, it will take a long time to figure out how the beast actually works.

    Great systems are simple, easy to understand and easy to modify.
    Test: give the system to a junior programmer and ask him to implement a change. Start the clock and see how long it takes.

    12. Clever code

    Code written by “gurus” can be a real PITA. Some gurus don’t like to comment their code and they can come up with really complex solutions that are difficult to understand and maintain. The good intention might be to make the code as short as possible but that might not be the right goal. KISS please!

    13. Managers who want single point effort and schedule estimates (actually promises) with 1 hour accuracy

    Need I say more?

    14. Noisy open offices with a bunch of people who are in no way involved in the project you are working on.

    This is a real productivity killer.

  116. Felipe Giotto said:

    Just great!! You made my morning happier!!! I’ll remember this post the rest of the day!!

    Felipe Giotto.

  117. I used to hate all code that was produced 3-6 months prior, but now I write code that stays fresh forever (ya right).

    Great article, twas enjoyed

  118. Tim H said:

    I agree on all points *except* #1. My favourite jobs involve going back to my old code from years ago, it’s like coming home to a house I built myself and lovingly furnished but never got to live in. Sure, maybe I would have done things differently but just as often I’m surprised at my own ingenuity and relearn things I’d forgotten.

    (I’m not sure if other maintainers feel the same way, however!)

    • Simon2 said:

      Yes, I feel the same.

      Often you develop something under tight deadlines and with no real specifications or design and then the code creep; developers were never involved in the selling process of non-existent features so you can’t go ask the customer what the specifications should be and the sales team has no idea. Lack of documentation means the developers then make best guess at interfaces and API’s and make assumptions about business processes. So, when with hindsight, you can revisit something you did under those conditions you can rebuild it with better understanding. I so infrequently get that opportunity.

  119. Elowie Cruz said:

    “There’s always a better way” – Thomas Alva Edison.

    Finding better ways to do things always excite me.
    I agree on all points as well as will #1. But Tim H, has a point. Usually, before we could get to the better code, we start with a prototype and as we develop it, the code just keeps getting better and better.

    Though we have to move along with technology and at the rate of Moore’s law, imagining all the possibilities makes me enthusiastic about the future.

    Very nice article, I even sent a msg of point #9 to my gf. hahaha!

  120. Jonny said:

    I love my old code. I’m often impressed when I look back what I did.

  121. This is the best article I have read in a LONG time. Everything you says is so true. especially #8 and #2. Its sad that programmers aren’t friendly to each other in the working environment. It often slows down the process on coding.

  122. Abulafio said:

    I TOTALLY agree with you!! Really nice, fun and damn actual article!

  123. TheAL said:

    #2 is especially a problem because of “Programmer’s Ego.” Overall, good list! I can pretty much relate to them all. Scope creep is especially nerve-straining as a freelance web developer. Spending an extra month coding staff login functionality or converting their ancient access database into a slick, new mysql one that’s actually normalized and works on the new site – all for free, and just because they only later remembered they needed it – nooooooooo fun.

  124. Cristian said:

    That “my code’s compiling” part just made my day! :))) That’s so real-life!!!

  125. Fantastic list and I agree with all of them.
    Like others have mentioned, I would also include other people’s code – no end of times I have been so tempted to rewrite what someone else has written.

    • Simon2 said:

      Once I was allowed to because of a performance problem. I reimplemented a tree data structure implementation written by the lead developer which had >10 classes as a hashlist of hashlists. It was very rewarding because the performance issue was solved and with 1 class with less than a page of code was required.

  126. Amy said:

    Great article! I agree with everything on here. I was reading it thinking OMG YES!!

  127. Asrar said:

    I agree with all the points in this article.

    I would add “spelling mistakes” to the list as well.

  128. I’d agree with #1. I’ve written the same web app 3 times. Although I really didn’t know much the 1st time as I was new to it. But after reading some practice books, version 3 is great. Now just to see if I feel that same way in 6 months.

  129. K|O|G|I said:

    I would have to add a point to #2… Programmers who think their code is perfect and that there is no possible way there could be something wrong with it.

  130. Irina said:

    Haha! Nice one!

    Correcting other peoples code should be in there too. When the things are done differently than you would do them. I find that very annoying.

  131. Kenny said:

    #3 reminds me of a call I got quite a few times at a previous job. I’d answer the phone and hear, “What the heck is wrong with this darned system?” (I cleaned it up a little.)
    I would give the only response I could: “O.K. Who the heck is this, which darned system are you talking about, exactly what the heck were you expecting it to do, and exactly what the heck did it do instead?”

  132. Dave H said:

    #1 should be a rite of passage for all new graduates who think their degree qualifies them to write software. Give them a job to do, then when it’s been finished for six months, get them to go back and do some non-trivial modifications to their own code. It also teaches them #10 and #6 on the list, because if they’ve done it properly, there will be enough clues in what they wrote first time to bring them back up to speed without having to reverse-engineer their own code. I know it brought it home to me that was what so obvious that I didn’t need to write it down was very obscure when I returned after a few months working on something else.

  133. Mouse said:

    What was true in August 2008, the date of the article, is still true today. That is what’s most compelling here.

  134. A great list…

    Everyone would be interested to know that two new studies have been released that demonstrate that the multi-tasking world we now inhabit is highly unproductive.

    Trying to get quality work done while constantly being interrupted is near impossible but now there is proof as to why…

    See the link… http://blogs.hbr.org/bregman/2010/05/how-and-why-to-stop-multitaski.html

    The link also provides access to the two reports…

  135. Jauler said:

    I partially disagree with #4.
    if your main tool is a computer (quite a tool!), then you should know how it`s working, and you should not only care about compiling your code, but also you about what it is becomes after compilation. And it should be able to use as much existing hardware as possible (for example hardware decoding/encoding) of course, this applies more for embedded systems, but every programmer at least should know assembler.
    But I have to admit hardware problems annoys programmers.

  136. Kado said:

    great blog ….what i hate the most is scope creep….that’s why you always have to do contracts.

  137. Elio said:

    well, i will just say that everyone of these things do annoy me all the time :P specially number 1 :P

    i would like to see a 10 things that annoy a programmer from their fellow programmers, one of them would be:
    Having to check out someone else poorly written code and modify it.. even if it has comments

  138. Mike said:

    Brilliant observations. Glad someone took the time to sit down and codify these things. I am going to keep a copy so as not to forget.
    Thanks Again

  139. MKB said:

    Dave H is so right. After 20 years of correcting my own and others code, any day I write code is considered a waste if I don’t learn something new.

    As for Bismark, if you are really that good; suggest you go to work for one the companies writing OS’s and clean up their crap so the OS is leaner and more secure.

  140. Herbie said:

    Did anyone mention inherited code? Something that someone else wrote years ago in a language that you hate to use and that you have to update in a hurry?
    I seem to spend my whole life doing that.

  141. Scott said:

    Don’t forget the classic, “Solving problems which don’t exist”.

    We’re all guilty of it. We get a request, then think to ourselves, “wow, it would be really cool if, while we’re in there, we just made it ‘better’ by also doing x, y, z.”, which aren’t necessary for the project, then ending up with a more complex codebase than we really need.

    Sometimes, just solving the problem that’s presented is enough.

  142. Jack Evans said:

    I have a different top 10 list. It goes:

    1. Software vendors who deliver buggy v12.x software.
    2. Hardware vendors who deliver under-performing, over-hyped hardware.
    3. Managers who think they are experts in everything.
    4. Co-workers who don’t know how to do their job.
    5. Team leaders who call all day meetings 5 times a week to try to find out why the project is behind schedule.
    6. Marketing staff who say “we could sell a gazillion of this product if it just….” (and then still don’t sell anything.)
    7. Customers who want to haggle on price after it is installed.
    8. Sports-jock type men who bluff, bluster or bully their way trying to get what they want.
    9. Women who flirt, cry or show their boobs to get their way. (On second thought, showing their boobs is OK.)
    10. All other people who do not fit in any of the above categories.

  143. vikram said:

    GreaT FindingS!

  144. ManfredP1961 said:

    great, 100% true espc. #1 – really enjoyed it – thanks :-)

  145. Dave said:

    I agree totally with that list.

    I’d add one however which really gets me down….weak specs. This could be attributed to #3, #5, #7 and #8 but is really a category all its own. I hate it when I’m tasked with making a report or an application and I’m given a really weak specification and told to get it done. I then have to fill in the blanks hoping that I’m giving them what they want. This typically happens when a programmer or IT manager is not involved in hashing out the original spec.

  146. Conan said:

    Jacks list is pretty good. Very insighful and gets closer to the heart of the matter (its all foo bar).

  147. Michal said:

    The most annoying is to deal with huge 20 years old codebase building into clump of miraculously interoperating applications and take care about all the undocumented hidden dependencies in it, all the additional solutions put wildly in code, all the versions of the functionality solving the same thing slightly different way spread in it, and search for the original concepts overgrown with fixes and enhancements added under a time pressure by programmers not having clue about these original (and not effective now) concepts and also having nobody to ask about it, because those orignal architecture folks are somewhere else for years (and they know very well why).
    And on top of this all there are customers used to use the huge system the way it works and are even proud about knowing how to workaround problems there and fighting against you (together with product management) if you want to bring some order back into the applications and reorganize things so that they are internally and externally more logical, clean, usable – no, they will not accept such change.
    And specs for new functionality does not follow internal logic at all – they follow customer’s wishes and are often pretty specific (and logically wrong).
    And also do not forget that many hard-to-understand special optional enhancements were done for specific customers with “special needs” in the system, so making logic more common removes the added value, though for you it is mostly just an added complexity making you desperately powerless… and annoyed.

  148. 2technical said:

    This is all true! I could add more, but i wont.

  149. Dave said:

    Good list and article. The same is true as it was 30 years ago. SSDD. different decade.

  150. Chris said:

    Yeah, what Mickey said :) Steven Johnson’s book Emergence identifies the “Crank” persona as one whose purpose for blog posting is some sort of complaint for the sake of denigration, or who always has an axe to grind. I think if there are software practices that work well, are repeatable, and constructive, then I’m open to listening; unfortunately I found Dan’s comment non-useful, but Kevin’s was quite informative. and practical.

  151. f_hampshire said:

    Excellent article. two true stories: (salesman wanting a software package to control dozens of physical properties on a manufacturing line) “Well, no, I don’t know what they want, but I took a deposit on it so can’t you just write the program and I’ll let you know later what I want it to do?” (salesman ((Yes, he’s dead, No, I did not kill him)) calling me on the phone) “Do you ever watch Star Trek? Good. You know they have this box that they point at something and it tells them all about it? Tricorder? Right. (my backside is tightening up at this point) Well, I know that’s in the future, but can you build one out of today’s components? Because I already took an order and have a deposit”

    • Kamau wa njoroge said:

      @ f_hampshire. Lolest. Tricorder eh!

  152. ed said:

    really cool !!!!!

  153. Jportela said:

    I loved the “interruptions” point, man I get stroke by interruptions constantly and I can really “feel” what you mean in here!
    I would also like to add “deployment configuration”. Sometimes when you go to the client facilities to deploy your application, the servers or clients are not configured as they were supposed to and even if you sent an email 2 months ago asking for them to do it so …. so you end up configuring the clients servers and clients…!

  154. Michelle said:

    That’s a pretty good list. Here is another that I can think of off the top of my head:

    “It should be simple to …”

    The client suggests a change they would like to see using the phrase it should be simple to … What they don’t realize is that this “simple” change could actually require a major rework of some functionality. At least by the time they finish reading the initial statement of work, they realize is is not simple to.

  155. MackanGyver said:

    It happens quite often that I experience the “who wrote this crap, oh, it was me”. But once, the greatest day of my life (almost) I thought, this code is brilliant, who wrote it? Oh it was me, yeey for me.

  156. Angry Programmer said:

    Architects. Enough said.

  157. Kalbintion said:

    In regards to #10, that example of code can be condensed much more and was poorly designed to begin with. Below is four different sets of code. All doing the exact same thing. The first three are my improvements upon the code, while the fourth is the original code from the original site. 22 bytes of code optimization. (difference in length from fourth and first codes). While i agree comments that explain how and not why are bad commenting practices, not understanding how to optimize your code is bad enough in itself, creating unneeded variables (ie: r) doesnt help readability. If one was to mathematically go through the process by hand and reduce the formula as much as possible for each thing. You could save a lot of typing to be done and make it much more readable in most cases and even possibly get rid of unneeded lines of code that won’t be needing commented upon because they are no longer there. Less lines can help a reader understand the code more than not.

    // square root of n with Newton-Raphson approximation
    while ( abs( n / 2 – 2 ) > t ) {
    n = n / 4 + 1;
    }
    System.out.println( “r = ” + n );

    // square root of n with Newton-Raphson approximation
    r = n / 2;
    while ( abs( r – 2 ) > t ) {
    r = n / 4 + 1;
    }
    System.out.println( “r = ” + r );

    // square root of n with Newton-Raphson approximation
    r = n / 2;
    while ( abs( r – 2 ) > t ) {
    r = 0.5 * r + 1;
    }
    System.out.println( “r = ” + r );

    // square root of n with Newton-Raphson approximation
    r = n / 2;
    while ( abs( r – (n/r) ) > t ) {
    r = 0.5 * ( r + (n/r) );
    }
    System.out.println( “r = ” + r );

    • Simon2 said:

      You should go read the top 10 list again. You’re optimisation offers nothing and in fact makes it harder for a future developer to understand because if there were a bug here it less represents the original algorithm that the original coder copied (and the future coder will google it and find it), it is more obscure and harder to understand and most modern compilers are highly efficient at optimising code. Personally I would explain the algorithm in the comments if it were not obvious. Less lines does not make better code.

  158. Widianto said:

    #1, it happens a lot for me, to read my own code is a nightmare since i didn’t like to create comments for my lines of code. Sigh… Nice list anyway.

  159. Martha said:

    Nice list! feels like I’m not alone :)

  160. Ken said:

    I agree with 10. I had to look up “Newton-Raphson approximation” and have to admit the example code still doesn’t make sense because it is nothing like the formula to calculate the square root this approximation uses. After seeing the formula, I’m thinking “Yea, I sort of remember that.” On 2, yea, I remember this guy that was always coming to me and asking me to write his code. He just had to walk towards me for me to think “Oh sh….”

    The following code is terrible, it doesn’t properly test boundary conditions and given the wrong values and can go into an infinite loop. (Like Target being less than 2 or negative.) Oh wait, I’m irritated with a comment that says why it does something and then codes something that doesn’t look anything like the “why” reason given.

    FirstEst = Target/2;
    while (FirstEst*FirstEst > Target) FirstEst = FirstEst/2;
    offset = 1.1;
    while (offset > 1.001 || offset < .999)
    {
    ScdEst = FirstEst-((FirstEst*FirstEst)-Target)/(2*FirstEst);
    offset = FirstEst/ScdEst;
    FirstEst = ScdEst;
    }

    I can relate to reason 1 as well. Usually because I didn't document it, I know why, but no longer know what it is doing when it does work, but not quite what they want.

    I've also been guilty of creating my own scope creep. "This would be so much better if…" That isn't nearly as irritating as the manager saying that. I can see how co-workers might groan.

  161. Ken said:

    I love this one:
    // square root of n with Newton-Raphson approximation
    r = n / 2;
    while ( abs( r – 2 ) > t ) {
    r = n / 4 + 1;
    }

    This is a loop that either never executes, executes once with no relation to the square root of n, or executes infinitely because r never changes once in the loop.
    1. t=100, n=2 (r=1)
    2. t=100, n=205 (r=102.5,r=52.25)
    3. t=100, n=500 (r=250,r=126)

    Oh yea, you can always get it right if n=4 and t > 0.

    PS My example would work for 1 to 2 values, never work for negative numbers, I think it might get above 0.999 for 1, I haven’t worked out what it would do with numbers between 0 and 1.

  162. Kamau wa njoroge said:

    How true. Seems we all face similar issues worldwide.
    Nothing more annoying than being in an office with people who always interrupt you by asking for help with non programming tasks (excel formulas, ms-word) and yapping endlessly on the phone about their colic babies.
    Another major one for me is deadlines and requests by managers.
    Manager x will ask you during a meeting how long it will take you to add functionality y into the project. When you say k days, they will immediately grunt, saying that’s too long and haggle like in a market, to force you to halve the time, like they know anything about what programming functionality y involves.

  163. MM said:

    I agree with every point in this post… Good to know that I’m not alone :)

  164. billy777 said:

    similar to point 3): my pet hate, bad/useless error messages (Windows, anyone?)

    I once spent half a day, under client pressure, because the (absent) project manager had coded an exception routine that completely obfuscated all useful detail, then printed the magnificent error message “parameter error”!

  165. Thorsten said:

    “Rectal Cranial Inversion”…my new favorite term. My goal for today – try to incorporate this into a conversation at work.

  166. Agree with the 10 :P

  167. Azonei said:

    I couldn’t have come up with a more accurate list if I had a spec sheet. Even the cartoon was accurate. I can’t count the number of times I’ve sat looking at the screen with a blank stare in my eyes while a program was compiling – or sometimes with just the blank stare in my eyes for no apparent reason (usually following one of the many interruptions to perform another task as mentioned in #9).

    My only complaint: You described me so accurately that I no longer feel unique. I’m just another sheep in the herd. I think I hate you. :)

  168. BlueCollarCritic said:

    It would greatly benefit any sofwtare company to engage in teh pratice of using people with some development skills and more writing skills/education to produce documentation with the developer. The Developer knows teh code but not necessairly how to articulate it to others, in particular to non-programmers or in other words to end users. The professional writer can do this but they too need some understanding of development else they will not properly understand how to articulate what the developer is telling them.

    This would make a lot of people happy at every turn of this problem with software documentation.

  169. TheRealist said:

    some more:

    11. The fact that nobody above you and few if any at your level or the customer really realise the difference between whats involved in some serious problem solving with an elegant solution and a text change. If I worked 10 times harder or smarter it would not be seen. consequently to balance things you would have to work DOWN to your wage and not UP to your ability.

    12. Bending over backwards for a single customer and adding layers of complexity to a system for a whim requirement that doesnt justify what it will take to make that happen, because no one (sales) wants to say no. then they never use it

    13. Technical Triumph followed by Commercial Disaster due to being told to code something pointless in the first place. Followed by a rush for the next “Golden Egg”

  170. TheRealist said:

    14. Receiving a tech/func spec that has more holes than swiss cheese and more loose ends than a persian carpet, then having to deal politically with the authour whilst I tear it up and start again talking directly to the stakeholder.

    True story:
    I worked for a company where salesmen got bonus on revenue brought in and not on profit. Salesman would sell projects under cost.
    (software costing, say, 10000 in coding time they’d sell for 1000 to make a commission of 100)

    One of these salesmen brought me a project to integrate all hardware and software within a conglomorate of 30 different companies (that had been bought up a single company). so thats Accounts, Human Resources, CRM, CMS, stock, inventory, servers, operating systems, licenses, everything.
    Tme allowed: 3 weeks.

  171. I really liked reading this article. I think that #10 is important. #7 is something that I have encountered a lot.

  172. tan4eg said:

    Hi Kevin! Russian version of your great list is here http://sly-and-fluffy.blogspot.com/2010/06/10.html

  173. Elia said:

    Perfect, man! Congratulations! Do you know if there is already a brazilian portuguese translation for that post?

  174. Good points, especially the first one about interruptions. I work as a BA and PM, and when I’m working on a document I definitely need some uninterrupted ramp-up time to get going.

    I recently started a position at a company that uses a SCRUM methodology, and the short morning meetings have cut down on interruptions considerably for the team.

  175. John said:

    Users – they are like the worst types of managers possible. Managers have to deal with you – that’s what they’re paid for. Users will just sit on your forums and whinge that you’re dropping support for an OS that hasn’t been updated since the Stone Age.

  176. sue7024 said:

    I’m a project manager, but used to be a developer, so I understand the pains of the above. . .very good list. . .where I work there is a sign that hangs as a constant reminder and reads “Always code as if the person who will maintain it is a violent psychopath who knows where you live”.

  177. Great article. I always use comments in my code evens if they are simple. It helps to find different things quicker and reminds me what things do and where i want to edit.