1. 42

subtitle: and how you can use the same techniques to reduce the number of bugs in your own software projects


  2. 16

    I’m especially fond of slides 80-94, which describe Hipp’s view on comments, how to use them, and why they’re good. Going to copy those slides hiere, just so nobody will miss them. Especially “comments make you express the same idea multiple ways” and “comments stand in for low-level requirements” are neat ways to think about them.

    Use Your Whole Brain
    • Math side
    • Language side
    Use Your Whole Brain
    • Code side
    • Comment side
    Why Put Comments In Code?
      1. Make the code easier to read
      1. Engage the linguistic side of your brain
    Code without Comments?
    • Only uses have [half] your brain.
    • In English we call this being a “half-wit”.
    Why Put Comments In Code?
      1. Make the code easier to read
      1. Engage the linguistic side of your brain Catch and fix code defects early
    [Cartoon, can’t read the creator’s signature]

    “Hey, Carl, can you look at this problem with me. I’ve been working on this for hours. You see the X variable clearly cannot be less than zero because Y has to be more than 20…. Oh wait. That’s not right. OK, I’ve got it now. Thanks, Carl!”

    Common Fallacy: “Well-written code needs no comments”
    • Ignores reason (2) for writing comments
    • No code is ever that well written
    What To Comment
    • Each function or procedure and major code blocks
      • Explain what it computes, not how it works
      • Preconditions, postconditions, invariants
    • Each variable, constant, and type declaration
      • Explain what the variable or type represents
      • Constraints
    • Comments stand in for low-level requirements
    • Be succinct – avoid fancy formatting and boilerplate
    Mother-tongue Or English?
    • English-language comments are best for readability.
    • Mother-tongue comments are best for catching bugs.
    • Why not do both?
    Code :: Comment (ratio in SQLite)
    • 53813 :: 27695
    • 2 :: 1
    Express Ideas In Different Ways

    [example image: both a Backus-Naur grammar and SQLite’s famous syntax railroad diagrams]

    1. 8

      At work, I have been wondering about the fundamental conflict between branch coverage and asserts during the last week: It makes no sense to write a test which checks the false-case of an assert. If you would remove the assert the code would be as correct as before but the test would fail.

      The answer of sqlite to this dilemma is to distinguish between the test run and the test validation via coverage. Asserts are removed during the coverage check, so there is no temptation to write test case for false asserts.

      The presentation explains this philosophy as “Measuring coverage validates your tests, not your product” and gives some concrete examples for ALWAYS and NEVER. Good stuff.

      1. 2

        Yeah this stuck out to me too, and reading their docs, it helps me make sense of something I hadn’t understood before:

        • a DEBUG build of software executes assert(),
        • but a PRODUCTION one doesn’t, and so
        • why do some programs use it as though for error checking or argument validation, when those go away in the build?

        The common example in the wild is something like assert( ptr = malloc(sizeof(int)) ); which is dangerous in release builds.

        SQLite’s solution is that assert() is more like a smart comment: You can use it to “enforce” contracts in debug builds, but it ALSO doubles as a reminder to someone reading the code that this value really must, yes, be defined.

        Given that, I actually have some software that could benefit from adding assert(): there are internal functions which call other internal functions, that originally were coded defensively like

        if(arg1 == NULL) { fprintf(stderr, "arg1 cannot be null\n"); exit(EXIT_FAILURE); }

        , but I started feeling silly programming defensively against myself. So then I went and took care to make sure the callers never pass NULL, and then I removed the argument validation, but now I feel unsafe again. assert() to the rescue!

      2. 4

        The postulate of ‘use your whole brain’: that you have a ‘math side’ and a ‘language side’ irks me. I relate to math and language in the same way: through language. Symbolically. Well, I still write comments. I still think they’re valid, and super useful, but I don’t relate to them in a fundamentally different way than code the way the presentation seems to suggest.

        1. 2

          Yeah as far as I’m aware there’s no evidence to suggest that the popular notion of having a math side and language side of the brain has any relationship to the actual structures of the human brain. Expressing the same concept in multiple ways by writing comments next to the code might well be genuinely useful for reducing the defect rate, but I’m put off by making too much hay out of that specific bran hemisphere metaphor.

          1. 1

            That’s a fair point; I, too, think of maths and code in large part through the filter of language. Then again, I definitely express myself differently when I limit myself to the vocabulary and idioms of maths or code, versus when I use language to get an idea across.

          2. 2

            The article title should reflect this is from 2009.

            1. 1

              It would, but it’s out of characters.