Code Complete

by Steve McConnell

Header comment that describes the class and provides any notes about the overall usage of the class Constructors and destructors Public routines Protected routines Private routines and member data

Code as if whoever maintains your program is a violent psychopath who knows where you live.

The common argument against commenting as you go along is “When you’re concentrating on the code, you shouldn’t break your concentration to write comments.” The appropriate response is that, if you have to concentrate so hard on writing code that commenting interrupts your thinking, you need to design in pseudocode first and then convert the pseudocode to comments. Code that requires that much concentration is a warning sign.

Comments can’t rescue difficult code. As Kernighan and Plauger emphasize, “Don’t document bad code — rewrite it” (1978).

This advice applies mainly to code you’re writing for the first time. If you’re maintaining a program and don’t have the latitude to rewrite bad code, commenting the tricky parts is a good practice.

Cross-Reference A stronger technique for documenting allowable ranges of variables is to use assertions at the beginning and end of a routine to assert that the variable’s values should be within a prescribed range. For more details, see Assertions.

If a loop is complicated enough to need an end-of-loop comment, treat the comment as a warning sign: the loop might need to be simplified. The same rule applies to complicated if tests and case statements.

Describe the design approach to the class. Overview comments that provide information that can’t readily be reverse-engineered from coding details are especially useful.

Describe limitations, usage assumptions, and so on. Similar to routines, be sure to describe any limitations imposed by the class’s design. Also describe assumptions about input and output data, error-handling responsibilities, global effects, sources of algorithms, and so on.

IEEE Software Engineering Standards Collection, 2003 Edition.

Code Reading: The Open Source Perspective.

We become authorities and experts in the practical and scientific spheres by so many separate acts and hours of work. If a person keeps faithfully busy each hour of the working day, he can count on waking up some morning to find himself one of the competent ones of his generation. — William James

Analyze and plan before you act. You’ll find that there’s a tension between analysis and action. At some point you have to quit gathering data and act. The problem for most programmers, however, isn’t an excess of analysis. The pendulum is currently so far on the “acting” side of the arc that you can wait until it’s at least partway to the middle before worrying about getting stuck on the “analysis-paralysis” side. cc2e.com/3320

Any fool can defend his or her mistakes — and most fools do.

A manager usually appreciates honest observations about the status of a project, even if they’re not the opinions the manager wants to hear. If your observations are well thought out, give them as dispassionately as you can and in private. Management needs to have accurate information to coordinate development activities, and full cooperation is essential.

If management applies pressure to change your estimate, realize that ultimately the decision whether to do a project rests with management: “Look. This is how much it’s going to cost. I can’t say whether it’s worth this price to the company — that’s your job. But I can tell you how long it takes to develop a piece of software — that’s my job. I can’t ‘negotiate’ how long it will take; that’s like negotiating how many feet are in a mile. You can’t negotiate laws of nature. We can, however, negotiate other aspects of the project that affect the schedule and then reestimate the schedule.

Programming is communicating with another programmer first and communicating with the computer second.

Many highly creative people have been extremely disciplined. “Form is liberating,” as the saying goes. Great architects work within the constraints of physical materials, time, and cost. Great artists do, too. Anyone who has examined Leonardo’s drawings has to admire his disciplined attention to detail. When Michelangelo designed the ceiling of the Sistine Chapel, he divided it into symmetric collections of geometric forms, such as triangles, circles, and squares. He designed it in three zones corresponding to three Platonic stages. Without this self-imposed structure and discipline, the 300 human figures would have been merely chaotic rather than the coherent elements of an artistic masterpiece.

The most important work in effective programming is thinking, and people tend not to look busy when they’re thinking. If I worked with a programmer who looked busy all the time, I’d assume that he was not a good programmer because he wasn’t using his most valuable tool, his brain.

Most of the time, persistence in software development is pigheadedness — it has little value. Persistence when you’re stuck

on a piece of new code is hardly ever a virtue. Try redesigning the class, try an alternative coding approach, or try coming back to it later. When one approach isn’t working, that’s a good time to try an alternative (Pirsig 1974).

“If I don’t solve the problem using this approach within the next 30 minutes, I’ll take 10 minutes to brainstorm about different approaches and try the best one for the next hour.”

Gonzo Programming If you haven’t spent at least a month working on the same program — working 16 hours a day, dreaming about it during the remaining 8 hours of restless sleep, working several nights straight through trying to eliminate that “one last bug” from the program — then you haven’t really written a complicated computer program. And you may not have the sense that there is something exhilarating about programming. — Edward Yourdon This lusty tribute to programming machismo is pure B.S. and an almost certain recipe for failure. Those all-night programming stints make you feel like the greatest programmer in the world, but then you have to spend several weeks correcting the defects you installed during your blaze of glory. By all means, get excited about programming. But excitement is no substitute for competency.

Habits The moral virtues, then, are engendered in us neither by nor contrary to nature…their full development in us is due to habit….Anything that we have to learn to do we learn by the actual doing of it….Men will become good builders as a result of building well and bad ones as a result of building badly….So it is a matter of no little importance what sort of habits we form from the earliest age — it makes a vast difference, or rather all the difference in the world. — Aristotle Good habits matter because most of what you do as a programmer you do without consciously thinking about it.

Bill Gates says that any programmer who will ever be good is good in the first few years. After that, whether a programmer is good or not is cast in concrete (Lammers 1986).

You can’t replace a bad habit with no habit at all. That’s why people who suddenly stop smoking or swearing or overeating have such a hard time unless they substitute something else, like chewing gum. It’s easier to replace an old habit with a new one than it is to eliminate one altogether.

The characteristics that matter most are humility, curiosity, intellectual honesty, creativity and discipline, and enlightened laziness.

Surprisingly, raw intelligence, experience, persistence, and guts hurt as much as they help.

Good character is mainly a matter of having the right habits. To be a great programmer, develop the right habits and the rest will come naturally.

The main reason the process matters is that in software, quality must be built in from the first step onward. This flies in the face of the folk wisdom that you can code like hell and then test all the mistakes out of the software. That idea is dead wrong. Testing merely tells you the specific ways in which your software is defective. Testing won’t make your program more usable, faster, smaller, more readable, or more extensible.

Level 1: Programming-Language Structures and Tools Programming-language structures are the language’s primitive data types, control structures, and so on. Most common languages also provide additional libraries, access to operating system calls, and so on. Using these structures and tools comes naturally since you can’t program without them. Many programmers never work above this level of abstraction, which makes their lives much harder than they need to be.

Level 2: Low-Level Implementation Structures Low-level implementation structures are slightly higher-level structures than those provided by the language itself. They tend to be the operations and data types you learn about in college courses in algorithms and data types: stacks, queues, linked lists, trees, indexed files, sequential files, sort algorithms, search algorithms, and so on.

Level 3: Low-Level Problem-Domain Terms At this level, you have the primitives you need to work in terms of the problem domain.

In many applications, this will be the business objects layer or a services layer. Classes at this level provide the vocabulary and the building blocks. The classes might be too primitive to be used to solve the problem directly at this level, but they provide a framework that higher-level classes can use to build a solution to the problem.

Jon Bentley’s Programming Pearls, 2d ed. (Bentley 2000) discusses the art and science of software design in the small. The book is organized as a set of essays that are very well written and express a great deal of insight into effective construction techniques as well as genuine enthusiasm for software construction. I use something I learned from Bentley’s essays nearly every day that I program.

Programmers at Work, by Susan Lammers (1986), is worth the search. It contains interviews with the industry’s high-profile programmers. The interviews explore their personalities, work habits, and programming philosophies. The luminaries interviewed include Bill Gates (founder of Microsoft), John Warnock (founder of Adobe), Andy Hertzfeld (principal developer of the Macintosh operating system), Butler Lampson (a senior engineer at DEC, now at Microsoft), Wayne Ratliff (inventor of dBase), Dan Bricklin (inventor of VisiCalc), and a dozen others.

Gerald Weinberg’s The Psychology of Computer Programming (Weinberg 1998)

Every manager of programmers should have his own copy. He should read it, take it to heart, act on the precepts, and leave the copy on his desk to be stolen by his programmers. He should continue replacing the stolen copies until equilibrium is established (Weiss 1972).

A final excellent overview of issues in software development is Software Creativity (Glass 1995).

Roger S. Pressman’s Software Engineering: A Practitioner’s Approach, 6th ed. (Pressman 2004), is a balanced treatment of requirements, design, quality validation, and management.

Construx Software’s Professional Development Ladder (http://www.construx.com/ladder/). This website provides recommended reading programs for software developers, testers, and managers.

IEEE Software. http://www.computer.org/software/.

Adams, James L. Conceptual Blockbusting: A Guide to Better Ideas, 4th ed. Cambridge, MA: Perseus Publishing, 2001.

Bentley, Jon. Programming Pearls, 2d ed. Reading, MA: Addison-Wesley, 2000.

Glass, Robert L. Facts and Fallacies of Software Engineering. Boston, MA:...

McConnell, Steve. Software Project Survival Guide. Redmond, WA: M...

McConnell, Steve. Code Complete, 2d ed. Redmond, WA: Micr...

Berczuk, Stephen P. and Brad Appleton. Software Configuration Management Patterns: Effective Teamwork, Practical Integration. Boston, MA: Addison-Wesley, 2003.

Fowler, Martin. UML Distilled: A Brief Guide to the Standard Object Modeling Language, 3d ed. Boston, MA: Addison-Wesley, 2003.

Glass, Robert L. Software Creativity. Reading, MA: Add...