The Greatest Compliment A Developer Can Receive

0 comments suggest edit

Here’s the dirty little secret about being a software developer. No matter how good the code you write is, it’s crap to another developer.

It doesn’t matter if the code is so clean you could eat sushi off of it. Doesn’t matter if both John Carmack and Linus Torvalds bow down in respect every time the code is shown on the screen. Some developer out there will call it crap, and it’s usually the developer who inherits the code when you leave.

The reasons are many and petty:

  • Your code uses string concatenation in that one method rather than using a StringBuilder. So what if in this one situation, that was a conscious decision because on average that method only concatenates three or four strings together. The next guy doesn’t care.
  • You put your curly braces on the same line rather than its own line as God intended (or vice versa).
  • You used a switch statement when everyone (including the next developer) knows you’re supposed to replace that with the State or Strategy pattern, always! Didn’t you read Design Patterns? Never mind the fact that there’s only one switch statement and thus no code duplication.
  • You’re using Spring.NET for dependency injection, but the next guy loves Windsor. Only idiots choose Spring.NET (or vice versa, again).
  • Or perhaps you used dependency injection at all. What the hell is dependency injection? I don’t understand the code now! :(

While we strive for perfect code, it is unattainable on real projects because real code is weighed down by the pressure of constraints such as time pressure. Unfortunately, these constraints aren’t reflected in the code, just the effect of the constraints. The next developer reading your code didn’t know that code was written with one hour left to deliver the project.

Although I admit, having been burned by misguided criticism before, it’s hard not to be tempted to take a pre-emptive strike at criticism by trying to embed the constraints in the code via comments.

For example,

public void SomeMethod()
{
  /*
  At most, there will only be 4 to 5 foos, so string concatenation 
  is just fine in this situation. Here are links to five blog posts that 
  talk about the perf implications. Give me a break, it’s 
  3 AM, I’m hopped up on Jolt, this project is 3 months
  late, and I have no social life anymore. Cut me some slack!
  ...
  */
  string result = string.Empty;
  foreach(Foo foo in Foos)
  {
    result += foo;
  }
  return result;
}

Seems awful defensive, no? There’s nothing wrong with leaving a comment to highlight why a particular non-obvious design decision is made. In fact, that’s exactly what comments are for, rather than simply reiterating what the code does.

The problem though, is that developers sometimes cut each other so little slack, you start writing a treatise in green (or whichever color you have comments set to in your IDE) to justify every line of code because you have no idea what is going to be obvious to the next developer.

That’s why I was particularly pleased to receive an email the other day from a developer who inherited some code I wrote and said that the solutions were, and I quote, “really well written”.

Seriously? Am I being Punk’d? Ashton, where the hell are you hiding?

This is quite possibly the highest compliment you can receive from another developer. And I don’t think it’s because I’m such a great developer. I really think the person who deserves credit here is the one giving the compliment.

I mean, my reaction when I’ve inherited code was typically, why the hell did they write this this way!? Did they learn to code from the back of a Cracker Jack Box!? Who better to serve as the scapegoat than the developer who just left?

Fortunately I had enough tact to keep those thoughts to myself. In the future, I’ll work harder on the empathy side of things. When I inherit code, I’ll assume the developer wrote it in a 72 hour straight coding binge, his World of Warcraft character held hostage, bees all over his body, with only an hour to finish the code on a 386 before everything really starts to go south.

Given those circumstances, it’s no wonder the idiot didn’t use a using block around that IDisposable instance.

Found a typo or error? Suggest an edit! If accepted, your contribution is listed automatically here.

Comments

avatar

43 responses

  1. Avatar for Omer Rauchwerger
    Omer Rauchwerger October 7th, 2007

    Phil,
    Great post, I agree, developers should strive to be more peaceful towards each other.
    But what about those developers who actually suck? Should we also forgive them or should we attack them by throwing Martin Fowler books and lists of references to blogs at them?
    -- rauchy.

  2. Avatar for Jon Limjap
    Jon Limjap October 7th, 2007

    You're lucky Phil. Hehe.
    The worst expletives that I've ever said about developers who left was when I found a whole system designed around a singleton that violated encapsulation and propagated circular dependencies within the whole system. Once I removed that singleton, I had to fix 700 compiler errors.
    The bad part was, the singleton was implemented by the OOP guru who I considered my mentor. I knew it had to be a really really bad deadline run for him to make that kind of monumental, err... "boo-boo".
    Other parts of a system have comments lamenting that "Test-driven development" has been replaced, unfortunately, with "deadline-driven development".
    Lesson learned: even Einsteins become Morts when faced with a deadline.

  3. Avatar for Leon
    Leon October 7th, 2007

    It's rare that we ever get any respect from our developer brethren in this day and age. Sadder still that instead of gleefully refactoring some tiny "boo-boo"'s from a friend's code base we call them up and tell them what d-nozzels they are. There have been many times when I've inherited some terrible code and in those times, if I know the dev I will honestly ask why they did some things. Most times, it's as you (or commenters) have said "I was in a hurry" or "my wife was in labor" or "didn't know any better at the time" or whatever. Otherwise, I let it go. And if I'm lucky enough that the person, more or less, made good choices, I usually take that person to lunch to learn more!
    I loved this article, Haacked. Sometimes mom is right, if you don't have anything nice (read: constructive or helpful) to say maybe it shouldn't be said at all. I've stopped apologizing for ever nit-pick thing that people can complain about and learned to embrace my personal coding dialect.

  4. Avatar for James Avery
    James Avery October 7th, 2007

    Agree completely on comments. Whenever I see comments that just re-iterate what the code does it drives me nuts, I usually just delete them. :) This is my favorite one that I see all the time:
    //Open the connection to the database
    using(conn.Open())
    {
    }
    Yeah, I understand what conn.Open is probably doing. :)

  5. Avatar for James Avery
    James Avery October 7th, 2007

    Right after I hit submit I realized my bad comment example didn't compile. But you know what I mean. :)

  6. Avatar for Josh Stodola
    Josh Stodola October 7th, 2007

    That sample comment was hilarious, and it reminds me of the way I comment. I sometimes get humourous in my comments just to lift the spirits of future programmers. I had to write a rather complex HTTP handler that did alot of different things. I put a comment at the top that said something to the effect of "Yes, I know at first glance this code just doesn't look right. But trust me, it is. Think I'm full of it? Call me at [cell number] or email me at josh420@josh420.com and I will set you straight."
    The handler isnt expected to change for a year or two, it will be interesting to see who gets it next! Hopefully I will get a compliment like you did. I thought it was well-written!

  7. Avatar for Kevin Dente
    Kevin Dente October 7th, 2007

    The really funny thing is how the same applies to our own code. How many times have you looked back at code you wrote a couple of years ago and thought "gah! what was I thinking?". ;)

  8. Avatar for Scott
    Scott October 7th, 2007

    "code you wrote a couple of years days ago and thought "gah! what was I thinking?". ;)"
    Fixed that so it applies to my code as well.

  9. Avatar for Haacked
    Haacked October 7th, 2007

    @Omer - For developers who do "suck", I refer to Jeff Atwood's advice.

  10. Avatar for orcmid
    orcmid October 7th, 2007

    Funny. The way that happened for me was a few years after I'd designed a mini-computer sidecar custom-billing process to a slow-to-change mainframe system. When they finally got around to incorporating the sidecar system into the mainframe, one of the developers met me by chance at an ACM meeting. You know, she said, I am converting your file designs to the IMS database, and it was so easy, almost as if you'd designed your solution for IMS. All I could do was grin.
    What had happened, along with documentation of the data design where she could easily abstract the essentials, was that I used two indexed files for record sets that were reciprocally foreign-keyed between the two sets. but I had carefully designed the insert-delete-replace rules so that failed transactions would leave tombstones but no links to nonexistent records. This was all accomplished by application logic. There was no DBMS, and I did no record locking.
    In working it all out, including the failure modes, I had used a hierarchical data model and she was benefitting from that in converting to a hierarchical DBMS. (It would have gone over to an RDBMS just as simply.)
    Of course, I'm sure there's someone who would insist what a dumb design that was.

  11. Avatar for Rob Conery
    Rob Conery October 8th, 2007

    A good friend of mine made a hobby of sweeping up after me (think parade, guy following horses) after I'd ninja a new startup or project. He was convinced (and still is) that I'm the world's biggest haack...
    I just tell him to get back to work :).
    Did you dis WoW? Don't be hatin on Azeroth buddy...

  12. Avatar for rektide
    rektide October 8th, 2007

    so what is the One True dependency injection container? Windsor or Spring.NET?

  13. Avatar for Pete
    Pete October 8th, 2007

    "Whenever I see comments that just re-iterate what the code does it drives me nuts, I usually just delete them."
    The point of comments isn’t just to explain tricky parts of the code. It’s also to make the code as quick as possible to read for the next person who ends up working on it. And, as it turns out... our brain is much, much, much quicker to process english language than it is to process Java or Pascal (or, most people’s brains are, anyway).
    And that fact alone makes it plausible to include comments, EVEN if they just re-iterate what the code itself does.
    Example:
    // Get Integer Array
    function GetIntegerArray(Array1: TIntegerArray; Array2: TIntegerArray): TIntegerArray;
    var
    Index: Integer;
    NewArray: TIntegerArray;
    begin
    // Set Length
    SetLength(NewArray, Length(Array1) + Length(Array2));
    // Add Array 1
    for Index := 0 to Length(Array1) - 1 do
    NewArray[Index] := Array1[Index];
    // Add Array 2
    for Index := 0 to Length(Array2) - 1 do
    NewArray[Index + Length(Array1)] := Array2[Index];
    // Result
    Result := NewArray;
    end;

    Same example without the comments:
    function GetIntegerArray(Array1: TIntegerArray; Array2: TIntegerArray): TIntegerArray;
    // Get Integer Array
    var
    Index: Integer;
    NewArray: TIntegerArray;
    begin
    SetLength(NewArray, Length(Array1, Array2);
    for Index := 0 to Length(Array1) - 1 do
    NewArray[Index] := Array1[Index];
    for Index := 0 to Length(Array2) - 1 do
    NewArray[Index + Length(Array1)] := Array2[Index];
    Result := NewArray;
    end;

    Out of these two, the first one is better.... EVEN if it contains comments which just re-iterate what the code itself does. ;)

  14. Avatar for James
    James October 8th, 2007

    I agree with Pete when he says "It’s also to make the code as quick as possible to read for the next person who ends up working on it. "
    But I disagree with his conclusions that that means add comments. The comments will likely start to lie after a while and the code will have a better chance of telling the truth over the long run. The blocks of code that Pete commented would be more expressive if they were extracted as methods, named to describe what is being done.

  15. Avatar for Gex
    Gex October 8th, 2007

    I'm a computer science major currently, and I try to read a lot of sites like this on programming. While participating on many sites and trying to understand some of the principles discussed in the article and comments, it struck me that the developer community is much more eager to act superior and mock someone than to bring someone along.

  16. Avatar for John Farrell
    John Farrell October 8th, 2007

    I've been working on the same Java development team for 10 years and developers come and go. It's only the truly great ones whose code survives after they leave. Everyone seems to have their sacred cows that are slaughtered as soon as they leave, and the code takes the form desired by those who remain.

  17. Avatar for Wendy
    Wendy October 8th, 2007

    Great post. Thanks.

  18. Avatar for Uncle Bob
    Uncle Bob October 8th, 2007

    I once read the following in a real comment:

    // I'm sorry for what is about to follow, but it's 2AM and I can't
    // do any better.

    For my money he could have done better. He could have gone home, gotten some rest, and then come back refreshed and finished in much less time.
    There is no excuse for writing sloppy code. Sloppy code slow you, and everyone else who has to read it, down. The cumulative effect of sloppy code is far greater than the benefit the author perceived when he made the mess.
    And don't give me that old "time to market" saw. Nonsense! Clean code makes you go fast. The only way to go fast is to keep your code clean! Messy code always slows you, and everyone else around you, down.
    No excuses. No mess. Keep your code clean.

  19. Avatar for John Lopez
    John Lopez October 8th, 2007

    I think a key to being understanding when you encounter "sub optimal" code quality is to read some of your *own* older code. Especially code written while learning a new technology.

  20. Avatar for Brian LeRoux
    Brian LeRoux October 8th, 2007

    Great post! Happens all the time.
    Anyone who takes the time to criticize should probably have the time to fix the issue and, if possible, let the originating developer know they found a trivial issue and thought they might be interested in a slightly better way. There's nothing wrong with *constructive* criticism. A good developer will appreciate it! Its all about being professional and treating others with the respect you'd like to recieve.
    And hey, Bob, I've always found stringbuilder less clean. I see your remarks as classic truisms and lacking in substance. Honestly, the hundredths of milliseconds StringBuilder shaves in performance is a very poor reason for extra characters. Using operators for concatenation *is* easier to read and therefore 'clean'. I really hope you guys have bigger fish to fry than performance optimizations from string concatenation!

  21. Avatar for Scott
    Scott October 8th, 2007

    Hey Bob.
    If you can show me a list or formula for producing clean code that every developer agrees on. I'll follow it!
    Heck, if you can just get every developer to agree on where the damn brackets go I'll vote you in as "President of developers".

  22. Avatar for Pete
    Pete October 8th, 2007

    James: "The blocks of code that Pete commented would be more expressive if they were extracted as methods, named to describe what is being done."
    It's a balance....... I try to factor my code so that no function becomes larger than 30-40 lines of code. Also, I try to factor it so that each function performs only a small number of operations (5-6 operations).
    Within those limits I think it's ok to keep multi-line operations as inline code blocks rather than breaking them out as separate functions.
    Also... I don't think there's any big difference when it comes to code deterioration. Method names can start lying too, just like comments can. There's no real difference.

  23. Avatar for Joe Grossberg
    Joe Grossberg October 8th, 2007

    IMHO, an even greater compliment is when another developer likes your code so much that they build their own software on top of it.
    Example: Edward O'Connor (hober) wrote a JSON library for emacs. That library is now used by the Twitter and Facebook libraries for emacs.

  24. Avatar for mike
    mike October 8th, 2007

    You lost me at


    You put your curly braces on the same line rather than its own line as God intended.


    Obviously, you were picking sides here and wanted everyone to know it.
    There is this little document published by Sun called Code Conventions for the Java Programming Language and it clearly places the bracket on the same line as the method signature.
    Recall that industry standards > organization standards > team standards > personal standards > no standards.

  25. Avatar for Haacked
    Haacked October 8th, 2007

    @Joe - Totally agree.
    @Mike - I'm not a Java programmer. My personal tastes is bracket on its own line except in the case of code within a view template file. That seems to be the general C# convention, though I'm sure many will disagree. My point is neither choice is the "Right" one, but developers have a tendency to let what is really a trivial decision lower their esteem for another developer.

  26. Avatar for Pete
    Pete October 8th, 2007

    Putting curly braces on separate lines is called Allman style.
    From Wikipedia:


    A disadvantage of this style is that each of the enclosing braces occupies an entire line by itself without adding any actual code. This once was an important consideration when programs were usually edited on terminals that displayed only 24 lines, but is less significant with larger resolutions.



    The motivation of this style is probably to promote code readability through visually separating blocks from their control statements, deeming screen real estate a secondary concern.



    This style is used by default in Microsoft Visual Studio 2005 and Apple's Xcode.
  27. Avatar for Pete
    Pete October 8th, 2007

    Putting curly braces on separate lines is called Allman style.
    From Wikipedia:


    A disadvantage of this style is that each of the enclosing braces occupies an entire line by itself without adding any actual code. This once was an important consideration when programs were usually edited on terminals that displayed only 24 lines, but is less significant with larger resolutions.



    The motivation of this style is probably to promote code readability through visually separating blocks from their control statements, deeming screen real estate a secondary concern.



    This style is used by default in Microsoft Visual Studio 2005 and Apple's Xcode.
  28. Avatar for ses5909
    ses5909 October 9th, 2007

    Nice post Phil. I'm no sh!t hot programmer but I do try, but I think we have ALL been guilty of writing crappy code as well as judging people for it.

  29. Avatar for mike
    mike October 9th, 2007

    My apologies, I was rereading the post, and realized that you were not a Java developer, in which case, the standard in M$ land seems to be bracket on its own line.
    Great post btw. Very insightful and true.

  30. Avatar for James Grenning
    James Grenning October 9th, 2007

    Pete:
    I think that developers are trained to ignore comments. They often don't get maintained like code does. But method names are another story. It is hard to ignore function names. You have to read them while navigating the code. Tge same is not true of comments. A wrong method name is hard to ignore.
    My goal is that functions should be be able to fit in your head within 30 seconds. Maybe not in detail, but enough to know if i have gotten to the place I wanted to get to.
    Getting code to work is one thing, making it understandable is another is the greater skill.
    I think the IDE writers have it right as comments seem to be fading into the background so we can focus on the code.

  31. Avatar for Pete
    Pete October 9th, 2007

    Ok... So you spend zero time maintaing the consistency of your own comments, and much time maintaing the consistency of your method names.
    I think I kind of understand why you don't trust other people's comments either.
    Personally I spend my time maintaing BOTH comments and method names. It takes a bit more time to write, but by doing it I'm able to grasp the meaning of my own functions in much less than 30 seconds, even when visiting them years after I first wrote them. I just browse through the comments in front of each code block, and I instantly can tell what the function does, without even looking at any of the code.
    It's a better way.... ;)

  32. Avatar for Member Blogs
    Member Blogs October 9th, 2007

    .NET My Introduction to Windows Workflow Foundation (WF) New Templates for WCF Development Enhancing

  33. Avatar for Uncle Bob's Friend
    Uncle Bob's Friend October 9th, 2007

    I completely agree with Uncle Bob’s comment.
    There are ways to improve code quality, specifically pair programming. There is no excuse for sloppy coding!
    Sure, as developers we can cut other developers some slack, but more importantly we as developers must concentrate finding ways to deliver cleaner, more readable and highly efficient code.
    Re-factor mercilessly! Plan this re-factoring into your project! Pair up!
    The problems depicted by this article are prevalent in waterfall style software projects of the 90s, where you would have scenarios where some cowboy developer (possibly me in a past life) would shoot off into the distance coding a deliverable in isolation for 2 weeks only to come back and have their sole ripped out of them by everyone else in the project for the bad quality work. It’s not fair on the developer and its irresponsible of the development managers.
    These problems don’t exist, or at least are extremely rare when using more current development methodologies that are based on XP techniques.

  34. Avatar for Mike
    Mike October 9th, 2007

    Ok, I can forgive the concatenation. But your code uses String.Empty instead of "" which is clearly the way Buddha meant it to be!

  35. Avatar for James Grenning
    James Grenning October 9th, 2007

    Pete:
    I do maintain my comments. I just write very few. Well factored code, written, or at least reviewed, in pair programming sessions does not need much in the way of comments.
    Comments are generally viewed as a weakness unless 1) they are describing some weird thing that can't be made better through refactoring and meaningful names. 2) The comment describes the responsibility of a class.
    The code within a method should not need comments. Where you find a comment you can still tell the code's story by extracting the method, and naming it so the comment's tale is told.
    Comments can be a form of duplication. Why write in a comment what is already in the code. One reason is if the code is not obvious. So instead of adding comments, I would 'code' my comments into the names of methods.
    I guess this is the crux of Phil's post, people have differing opinions of good code.

  36. Avatar for Chad Myers
    Chad Myers October 9th, 2007

    "I found a whole system designed around a singleton that violated..."
    I did that once. I still get dirty looks when I go out to lunch with the guys from that place I used to work at.
    I didn't know about TDD back then :(

  37. Avatar for SteveJ
    SteveJ October 10th, 2007

    Pete and James:
    I think this falls under a basic learning/brain style. I only read comments if I don't understand the code. My thinking style is much closer to code than vernacular text. I also ignore pictures and diagrams in books. Give me a huge interface description document and I'll chug along. Make me stare at a uml diagram and my brain will freeze up. I'm obviously wired a little different than my awesome coworkers that can take a complicated concept and reduce it to a ppt slide.
    So you see my bias, but I do think methods are better just because you have to type those letters in order to use that code. The compiler won't force me to read the comment. But if you maintain your comments, good for you. I'm sure your coworkers love you.

  38. Avatar for CodeObsessed
    CodeObsessed October 11th, 2007

    This gem is in the comments, 2nd one down. Lesson learned: even Einsteins become Morts when faced with

  39. Avatar for Pete
    Pete October 13th, 2007

    "Comments are generally viewed as a weakness unless 1) they are describing some weird thing that can't be made better through refactoring and meaningful names. 2) The comment describes the responsibility of a class."
    Yeah, well, you know, that's just, like, your opinion, man.
    Anyway.... I think you miss out on the potential usefulness of comments as a bulleted list of what a function does. Using comments in this way makes it possible for new programmers to grasp the logic of a function (much) more quickly than if they had to read the entire code.
    Here’s an example by Christopher Seiwald, illustrating this point (copied from his book Pillars of Pretty Code):

    // Unlink a Record from a linked list
    Status
    unlinkRec(
    Record **list,
    Record *const rr )
    {
    /* Previous record *p is for unlinking. */
    /* Current record *r scans list. */
    Record * p = 0;
    Record *r = *list;
    /* Scan list for rr. */
    while( r && r != rr )
    p = r, r = r->next;
    /* No r? rr not found. */

    if (!r )
    return ERR;
    /* Delink r from list. */
    if( p ) p-> next = r->next;
    else *list = r->next;
    r->next = 0;
    return OK;
    }

    Without the comments the logic of the function would typically take about 45 seconds to induce for an average programmer. WITH the comments, the logic can be grasped in 5 seconds.
    This is the point which I was trying to make.

  40. Avatar for Andy
    Andy October 24th, 2007

    Ah, but what about when you look at code you wrote two years ago, and you KNOW you weren't suffering from sleep deprivation, and still you wonder what the hell you were thinking!

  41. Avatar for JM
    JM October 26th, 2007

    I vote for comments, verbose comments. It helps the man who comes behind.
    While reading code directly is fine for Wiz Bang stars it is faster for us mortals to read the comments.
    Comments let us understand what the programmer was trying to do, rather than what he did do.... We would not be looking at this again if there was not some problem with it, or it did not need a modification.
    Often we need to modify it because it was not as Wiz Bang as it could be or not encapsulated into a callable function, or failed to handle the errors and exceptions that the code gets in the real world.
    The man who comes to do the code maintenance my be new to the language, or new to the platform, or just new. Comments help them figure out what the code does, what the coder was trying to do, and how the code interacts with the data and business process.
    The original coder probably got a word view from design documents, demo code, test code, system test, user testing, etc. They lived with the process for months and so their brain thinks the business process that is coded into the code. The poor sod who is dropped in a cube and told to fix, modify or extend the code has none of this rich brain history.
    For him the only thing that illuminates the code are comments.
    Having been on the receiving end of the process, I can tell you that I have never had code handed down to me with too many comments but have often had WAY to little.
    If by chance, one day, I do get code with to many comments I will deploy a skill that I learned in school, I will skim them looking for what is relevant to the problem at hand.
    Personally, I have often found my self scratching my head, re-reading the code and the comments and still not understanding the scope of the thing, until I have worked on it some more.
    I often find my self adding to the prior comments to make it abundantly clear as to what is going on.
    I have programed for money. This normally means that I have a boss, and the boss wants to revue what cost him so much. With a well commented code I just hand in the code and go home, knowing that even if I don't know the most optimal way to do something, the boss will perceive, through the comments that progress is being made and that the code is leading to the business solution, or fix de jour.
    Back when I coded for the IBM basic compiler version 1.0, when the size of your input code was a factor, then it was wise to keep comments in hand. Since then, source code file size has not been an issue and I can find no good reason, other than showing you are a Smart Ass, for not fully commenting your work.
    Better 50 lines of code well commented than 200 that are miraculously "self evident", or that appear so to the original coder.
    If you are capable of miraculous stuff then you are in the wrong business, for the Catholic Church is desperately in need of your services.

  42. Avatar for Khebbies blog
    Khebbies blog November 5th, 2007

    Om at overtage andres kode

  43. Avatar for minus Seven
    minus Seven June 6th, 2014

    I put curly braces in the same line as the code. I wonder what can be wrong with that .........