Monday, June 11, 2007

Coding for Humans

For this class I'm in I have to read Smalltalk Best Practice Patterns by Kent Beck.  He has an interesting quote in the first chapter.  He says, "[W]hen you program, you have to think about how someone will read your code, not just how a computer will interpret it."  He's right.  The biggest thing I see in new programmers (either new graduates or newly self-taught coders) is that they don't understand maintenance.  In school you never have to revisit a program after you hand it in.  In writing your own code, you don't often revisit it a long time later and you rarely change someone else's code.  In industry, there's a lot of work on old code.  For instance, we have a test shell that began life as a 16-bit application.  The code originally ran on Win 3.1.  That's old.  It has undergone a lot of changes since then and is now Unicode-clean, 64-bit clean, and fully object oriented.  However, some of the old code still survives.  The initial code I wrote to test DVD playback 8 years ago is still used daily.  If this code were written without thought to the next person, it would have been replaced with code that was.  It takes too long to read opaque code.  It's too easy to make mistakes when maintaining it.

Always write your code in the most direct manner possible.  If you can save a few processor cycles but will make the code harder to read, stop.  Write the obvious code until/unless a profiler tells you that code path needs to be optimized.  Even then, comment the code well.  Especially then, comment the code well.  The worst thing is to run into optimized code without comments.  It's sometimes not even worth trying to understand.


  1. New hires should get a copy of "Code Complete" on their desk when they come in - it goes a long way to helping them understand the need for maintenance in code.

  2. Amen, I had noticed that on enough of my own projects where I come back to something later that is done in a non-obvious way, not necessarily for performance or whatnot, but to work around a bug, and helpfully say to myself, "What a stupid way to do things, what's wrong with me" and change it to the 'normal' way only to find (or not find, or find out much later) that there was a reason for it.  So now I make sure to document why things are the way they are and comment out code with a reason rather than just removing it wholesale.  
    I now take the same principle to others' code, which is that, even if it's not well-documented, that other developers are not stupid, and that there's a reason they wrote it like they did (within reason).  I guess it's similar to Raymond's psychic debugging tip: when seeing unfamiliar code, assume it's mostly correct (

  3. have u read book Smalltalk With Style ? if not please download it from and read.
    It is collection of pragmatic tips for Smalltalk.

  4. Pingback from
    (Don't know why these things aren't automatic anymore)

  5. @Hiren - no, I haven't read that one yet.  I have read some of "Smalltalk Best Practice Patterns" by Kent Beck which seems to cover similar ground.