Patches and specs

From Leslie Lamport:

Every time code is patched, it becomes a little uglier, harder to understand, harder to maintain, bugs get introduced.

If you don’t start with a spec, every piece of code you write is a patch.

Which means the program starts out from Day One being ugly, hard to understand, and hard to maintain.

6 thoughts on “Patches and specs

  1. My only critique of this quote is its context/assumptions: It presumes you know enough about your problem to generate a useful spec.

    How is this known? When do you know you know enough to write a useful spec?

    The naive answer would be to keep writing specs (or implementing a hierarchy of specs) until you get a good one, which is just one level of abstraction up from Leslie Lamport’s comments about coding without a spec: It’s just patching. He does discuss debugging specs, but not much about the methods for doing so.

    The formal answer is to add another level of abstraction: Describe what a good spec should look like for this problem (often by writing a spec for the problem’s context), and check your initial problem specs for conformance to those goals.

    Unfortunately, it has been my experience that good specs can be derailed by subtle dependencies that arise during implementation, a non-uncommon occurrence in my specialty of real-time embedded systems.

    The path I choose is to first spec the “easy parts” (often re-using specs with the intent of re-using the associated code), then do research to learn more about the unknowns and create prototypes or models to validate that learning.

    It is easy to waste time when building prototypes by building too much, or by failing to build enough and having to try again.

    So, while Leslie Lamport urges us to “spec before coding”, I would embellish this to add “know when to experiment before committing to a spec”. I tend to think of a yo-yo model: If, after doing the initial research I find myself stuck (or lost) in the spec, I code a little to learn more (to verify my understanding of the problem, to learn more about it), then return to the spec.

    The only cautionary note I would add would be to prototype using tools unrelated to the expected development/delivery platform. Most often, I would deliver in C/C++. At large companies I prototyped in Matlab/SimuLink, and at small companies I used Python/Scipy (and friends).

    It is important to not permit prototype code to be included in the final project except by means of the spec, a principle I’ve adhered to for decades. Prototype code may be viewed as being free of the full context of the larger project, and including it can require more patching than high-level development would warrant.

  2. It depends if you refactor your code as you patch, in which case often the code becomes cleaner, tighter and easier to understand as you fix the bugs. This is where the real strengths of strongly typed and highly tooled languages such as java come into play, allowing you to refactor mercilessly without leaving the code a bug-ridden mess – even when not covered with decent unit test suite.

  3. When possible, I 100% agree that a good specification of the problem needs to be written. I spend far too much of my time bug finding though hacked code from someone who obviously started writing the program before having a good idea of the problem.

    Mistakes and bugs will always happen, but if the project is well organised from the beginning the bug are easier to fix and will happen less often.

    I’ve always said that I’d rather spend 50 hours at the start of a project and then 50 hours implementing the solution. Rather than 20 hours at the start and 100 hours implementing (and reimplementing…)

  4. I once read a quote (unfortunately I cannot find it right now), which was like: “Write a spec until you think you understand the problem. Then write code until you find out that you don’t. Then start over.”

  5. It’s more like diamond cutting: you have to start out with a plan that maximizes the value and weight of the stone but then you have to polish the stone until each face reaches its full potential and brilliance. Code that hasn’t been used and patched as a result of what you’ve learned while using it is like a diamond that hasn’t been polished.

    “In every block of marble I see a statue as plain as though it stood before me, shaped and perfect in attitude and action. I have only to hew away the rough walls that imprison the lovely apparition to reveal it to the other eyes as mine see it.” – Michelangelo Buonarroti

  6. Tell the 23 year old spotty kid at Google who interviews prospective software developers! In his inexperience he seems to think that your ability to answer a bit of trivia with a quickly put together code is the passport for joining his firm.

    How you write code and how others can second guess what you have done is more critical than the Google test because code must be maintainable, unless you have the talent and time to re-write it all again from scratch each time (maybe what Google is counting on), but that might also require creativity and stabs in the dark which their interviews do not seem to measure!

Comments are closed.