The Twelve Programming Truths

The Twelve Networking Truths (also known as the Twelve Fundamental Truths) were first collected and presented in RFC 1925. These were meant to apply to the practices of network architecture and engineering, and they are fantastic in that context. As my career transitioned from network architecture to driver development, I kept coming back to the Twelve Truths every so often, and each time I noticed their remarkable value even as adapted to software development.

Like the author of RFC 1925, I have by no means discovered or invented these truths, but after having trained a fair number of new software developers, it has become oblivious that these principles, as applied to computer programming, are generally useful and valuable.

With that in mind, I will discuss each of the Twelve Truths as applied to the craft of software engineering. It is my hope that you find as much value in them as I have. I hope that I haven't destroyed their impact with my attempt to adapt them to another discipline, although I'm afraid something is always lost in the translation.

Two acknowledgments must be made: first, to Ross Callon, who first assembled the Truths into RFC 1925 on April 1, 1996, and to Dr. Deep Medhi, head of the computer networking department at the University of Missouri - Kansas City, who first introduced me to the RFC.

   (1)  It Has To Work.

You'd think this Truth would go without saying, but in fact, sometimes it seems like the last thing on the minds of a room full of software engineers during design of a program. Much (most?) software development is done for money. Clients, employers, and customers all expect the code to work. They don't usually even care how it works (sometimes to the chagrin of the developers!), but It Has To Work.

There are a couple of subcases of It Has To Work. The first case is understanding the definition of "work". This word, like "done", gets thousands of connotations and definitions in various contexts, and there is nobody like a programmer to confuse these definitions. Your client may not have any use for your word processor if the spell checker gets exponentially slower with every word typed. Yes, the check may complete eventually, but it doesn't "work" for the customer.

Another aspect of "working" is completeness. I'm not the first to quote this concept, but my empirical observations have led me to conclude that it takes 50% of the time to do the first 97% of the work, and 50% of the time to do the last 3%. Around my office, we have the "Last 3% Rule" when it comes to project planning. It may be that the encryption algorithm works perfectly, but until the user interface "works" - all the buttons do the right things, the appearance is polished and professional-looking, it doesn't suffer from state problems, etc. - it's not done.

At my office, we don't declare something Working until it has passed our Quality Assurance testing. The QA team is a separate group of folks who are responsible for thoroughly verifying that the software's functionality. It doesn't Work until they say it does.

There's a reason this is Truth #1. Nothing else matters if it doesn't Work, in every sense of the word. Above and beyond everything else, Working software yields happy customers.

   (2)  No matter how hard you push and no matter what the priority,
        you can't increase the speed of light.

        (2a) (corollary). No matter how hard you try, you can't make a
             baby in much less than 9 months. Trying to speed this up
             *might* make it slower, but it won't make it happen any
             quicker.

The original intent of this Truth is to illustrate that there are laws (some from Physics, some from The Reality Of Life) that cannot be broken. In networking, system throughput is eventually totally bound by the speed of light, and there's nothing that even the most talented engineer can do about it, other than work around these inherent limitations.

The obvious application to software engineering is that software development takes time. It usually takes more time than the customer would like, and often takes more time than the developer would like (in particular, the Last 3% is usually pretty boring work). However, failing to understand this fact can only lead to one of three outcomes:

• The deadline arrives, and your software doesn't Work
• Your software Works, but you've blown the deadline
• (in some cases) The deadline arrives and the software Works, but you do not, due to chronic lack of sleep and food.

None of these are good outcomes, and all of them, in a bad enough case, can put a serious and permanent dent in your ability to earn money as a programmer. Also, that last case can only happen if the planning isn't off by more than the amount that you can make up by your superhuman effort.

Nobody is a perfect predictor of the time it takes to develop software, but you owe it to yourself as a programmer to give yourself a fighting chance of hitting your deadlines. This does *not* mean that you should plan on having to work tons of extra hours just to hit an un-hittable date. Rather, it means that you must work with customers, project managers, and anyone else who is interested, to make sure that expectations are set correctly up-front. There is no way out of this task, and all previous known attempts to get around expectation management have failed miserably.

   (3)  With sufficient thrust, pigs fly just fine. However, this is
        not necessarily a good idea. It is hard to be sure where they
        are going to land, and it could be dangerous sitting under them
        as they fly overhead.

I've heard a lot of bad ideas in my career. These ideas are usually the result of an overzealous engineer that doesn't quite understand the problem at hand, and doesn't really want to figure out the Right Way To Do It. In almost all cases, there is a right way and a large number of wrong ways to accomplish a given task. Wrong ways include everything from hooking Windows system calls in production code to hacking in a new feature in the 11th hour with insufficient design documentation.

Sometimes these tactics might work, for a while, but you will always suffer in the end.

   (4)  Some things in life can never be fully appreciated nor
        understood unless experienced firsthand. Some things in
        networking can never be fully understood by someone who neither
        builds commercial networking equipment nor runs an operational
        network.

Find an expert in any field of software engineering. There is virtually a 100% chance that he or she has written production code in that field. Code that has been sold to someone, or on which someone else depends in one way or another. If this seems obvious to you, consider the number of Monday morning quarterbacks. Software engineering has them too. Sometimes they are students, sometimes they are managers, sometimes customers, sometimes even professors. Whoever they are, if they haven't written production code they won't understand the practice of software engineering. If you are one of these people, recognize this fact and have some faith in your programmers.

There is a tangible difference between writing code for a class project, or even "just for fun", and writing production code. The best way by far to become a better programmer is to write more production code. Until you've gotten tech support calls, bug reports, feature requests, and (perhaps inevitably) patched vulnerabilities in your code, you're just practicing.

   (5)  It is always possible to aglutenate [sic] multiple separate problems
        into a single complex interdependent solution. In most cases
        this is a bad idea.

Good design is hard to find. It is a balance between generalization and perfection in the expression of a set of abstract ideas on the one hand, and being down-to-earth enough so as to avoid requiring the coding of lots of exception cases on the other. Good designs are possible with any design paradigm, and some are better suited to certain problems than others. Whatever your design paradigm, don't over-complicate the situation. As my grandfather used to say, "Don't make a Rembrandt!"

   (6)  It is easier to move a problem around (for example, by moving
        the problem to a different part of the overall network
        architecture) than it is to solve it.

        (6a) (corollary). It is always possible to add another level of
             indirection.

Rule 6a is one of the wisest things ever said. Many of the design problems I alluded to in Rule 5 above are really just this in disguise. Just remember - you have to pay the price for bad design eventually. If you find yourself encountering Rule 6, it's probably a pretty good sign that you need a re-design.

For added entertainment, notice that Rule 6a (about indirection) is itself a sub-rule. :-)

   (7)  It is always something

        (7a) (corollary). Good, Fast, Cheap: Pick any two (you can't
            have all three).

These Truths call to mind Rule #2 - there is no substitute for planning. Furthermore, there are problems that no amount of planning can solve. This is not really a re-formulation of Murphy's Law (although you should keep that in mind as well!), but merely a description of the peculiar art of software engineering. Things happen. Designs change. APIs don't work as documented. Oddball platforms don't support otherwise-universal interfaces. The list goes on, and by definition (and by Rule 7), you can't predict them. Better to keep this fact of life in mind during the planning stage of the project, and you'll have happier customers, spouses, partners, managers, etc.

Rule 7a needs no elaboration, other than to say that I have found it to be true over and over again. As a general principle, you cannot optimize Rule 7a away.

   (8)  It is more complicated than you think.

Much like Rule 7, this rule reminds us that human nature is to assume the straight-ahead case, minimizing the possibility that things could Go Wrong. People are just wired that way; there's no way around it. As a software engineer, you must be vigilant against the feeling that you completely understand your problem.

It was often said about the Theory of Relativity that only a couple of people in the entire world understood it during Einstein's time, despite the belief on the part of many that they had their brains wrapped around it. The bummer about this Truth is that it is usually not empirically obvious until after the painful process of learning has occurred.

One specific point about Rule 8 relates to the area of software security. Here, it takes more than best practices to write secure code. You must always maintain an attitude of extreme caution. It's extremely difficult to know if your code is secure as written. Lots of code that is secure in one environment turns out to have big holes in it in other environments. While there is no guarantee that this will prevent vulnerabilities, defensive coding practices and a general attitude of suspicion about everything you write will go a long way. I know I'm suspicious of everything I write. :-)

   (9)  For all resources, whatever it is, you need more.

       (9a) (corollary) Every networking problem always takes longer to
            solve than it seems like it should.

While Rule #9 has its obvious applications to software engineering, there is one particular uniqueness about software: often it is impossible to just "add resources" to a programming project. One reason is that the ramp-up time is often very long, even with an experienced coder. Another is that the complexity of adding a developer to a project tends to be O(n) with n = the number of programmers on the project. Furthermore, that implies that the "total complexity" of the project is O(n^2) [1]. Both of these numbers can be improved upon in practical cases with good design and organization of the project, but there's no doubt that small teams have an easier time being highly efficient.

   (10) One size never fits all.

This is another admonition against over-ambitious design. The natural tendency of the human (programmer's) brain is to generalize. Triumphs of generalization are everywhere around us, particularly in the realm of physical science. Other things, such as advances in hardware engineering, would be impossible without the art of generalization.

But, like anything, too much of a good thing ceases to be a good thing. One database developer I know is fond of saying that "the design cannot be so abstract that the database doesn't hold anything!" Often, inexperienced software architects over-generalize a design in their eagerness to arrive at the "perfect" solution. However, this is seldom possible. Software engineering is a real-world activity, where imperfections in design are a fact of life.

Sometimes it's okay to have one-off solutions. A skilled software architect develops a sense for how to minimize exception cases while maximizing the elegance of a design.

   (11) Every old idea will be proposed again with a different name and
        a different presentation, regardless of whether it works.

        (11a) (corollary). See rule 6a.

As the rule itself states, this is just another way to say Rule 6a. Be on guard against getting drug down the same old path again and again. It is a waste of time and money.

   (12) In protocol design, perfection has been reached not when there
        is nothing left to add, but when there is nothing left to take
        away.

Possibly the most valuable axiom ever contributed to the world's body of engineering knowledge. The same goes for software design - there is no need to overcomplicate software, and there is much need to keep it simple. Good software must be maintainable, and the less of it there is, the easier the task of maintenance.

Again, this rule runs against human nature - we like to build things - elaborate things - but nothing could be worse for software engineering. More than anywhere, software engineering requires the KISS principle.

Summary

I have long relied on the Twelve Truths, first in network engineering, and now in software engineering. There are few documents with as high of a concentration of practical wisdom as this one, and new engineers would do well to read and understand RFC 1925.

[1] "Proof" of the complexities of adding developers to a project:

Every coder has a certain amount of undocumented "state" in his or her head. This state is often a requirement for writing successful code, or at least is required to do it efficiently. It is this state that makes a group software development project complex.

Call the "amount" of this state X. If all n developers have X state in their heads, there is nX amount of undocumented state in the project. Each additional developer brings X more state to the project.

Each developer will eventually have to know the state in the heads of all of the other developers on the project (n-1)(X), requiring a total amount of "learning" of state of n(n-1)(X).

Therefore, adding a developer to the project (who starts with no state, but develops it over time) requires that developer to acquire (n-1)(X) amount of state, or O(n). The total amount of complexity in the project then rises to n(n-1)(X), as that developer adds his state to the project, which is O(n^2).