The Human Aspect – a Review of Code Complete

Steve McConnell’s Code Complete is one of these Classic Programming Books that feature on top 10 lists more often than not. It is universally praised and admired, and it’s a rather BIG book. So, is it any good?

Short answer: yes, it is very good.

Long answer:

Code Complete can be an intimidating book. At 850+ pages it covers a huge range of topics ranging from Metaphors via Collaborative Programming via character traits like Honesty and Humility all the way down to the Layout of code. So is it even coherent?

Yes it is. Code Complete imparts one main overarching theme throughout:

Software Construction is a human activity

Suddenly the wide range of topics makes sense. The human brain is a complicated thing, and human behavior has many different aspects. The author has valiantly – and successfully – tried to capture all of these different aspects and analyze how they are relevant to programming.

Some of the topics in the book that especially appealed to me:

The extremely interesting section about Metaphors describes various ways in which you as a human can think about programming (for instance: as a building project, as writing a book etc). McConnell clearly explains the pluses and minuses of each metaphor.

Software’s “Primary Technical Imperative” is Managing Complexity: no matter how smart you are, there are only so many things that fit simultaneously in a human brain, and as a programmer you’d better acknowledge this, and find ways to manage it (by design, conventions, abstractions etc). This feeds into what McConnell sees as the main character trait of a good programmer: humility. A good programmer acknowledges his/her inherent limitations and structures the work accordingly.

McConnell puts big emphasis on the importance of Process: how humans work together greatly affects the Quality of the end product and the efficiency and timeliness with which the end stage is reached.

The general principle of software quality is at first sight a paradox: improving quality – that means: investing extra time and money to improve quality – reduces overall development costs, because typically some 50% of time in a software project is spent on fixing mistakes. If you spend 10% more time in the beginning on the design, establishing common standards, reviews etc and that results in 20% less time needed on debugging, not only have you gained time and money, but the end product is better, more easily maintainable, extendable etc.

The actual technical guidelines for Software Construction (descriptive variable names, modularity, refactoring etc) are all focused on how to keep programs readable, understandable and maintainable for humans, including the original author of the code.

McConnell advocates writing in pseudocode first, and filling in the actual code around it. I find it hard to maintain that kind of discipline, but I will give it a fair try to judge its merits.

Sometimes his lists of possible improvements or actions are so extensive that they contain overlapping or even contradictory advise. For instance the checklist on Routine-level Refactorings lists both “Add a parameter” and “Remove a parameter”, both “Pass a whole object rather than specific fields”, and “Pass specific fields rather than a whole object” A reader looking for guidance can feel being left to his or her own devices, but of course these things depend on context, and there are no general rules that fit all cases. It also ties in with McConnell’s advocacy of eclecticism, non-dogmatism and an open mind.

Code Complete is well written, and at times even funny. Do the Data Literacy Test on page 238 and check out the commentary on the scoring!

A selection of nuggets of wisdom:

  • Set a maximum time for quick and dirty debugging.
  • See Defects as opportunities
  • When checking loop endpoints: use mental simulations and hand calculation rather than just random experiment
  • understand the problem before you fix it
  • hurrying to solve a problem is one of the most time-ineffective things you can do
  • Make one change at a time.
  • Write code for humans first, for computers second
  • The primary purpose of good layout is to show the logical structure of the code
  • Tricky code is bad code

Code Complete is both a great read and an invaluable reference. Essential!

Leave a Reply

Your email address will not be published. Required fields are marked *