1. 16
  1. 5

    Really liked the article, clear and concise! however i ended disagreeing with the disagreements.

    • A strong stance against exceptions

    Exception are good only for exceptional cases and not any non-favorable behavior. An http request failing is not an exceptional case but most systems treat it as such and create infrequent code paths which can lead to unforeseen failure conditions. (further anecdotal proof/opnion)

    • John is quite in favor of writing comments

    The post author’s stance is not in congruence with their agreement on deep modules. If a class/module has enough depth, it might require a why comment.

    1. 2

      Thanks for the feedback and appreciate you voicing your disagreement.

      For exceptions, the book seemed to suggest going out of the way to throw them. I’m not that dogmatic and don’t mind them - as long as there’s good monitoring, and we follow a zero-exceptions policy. So I’m more on the mitigation side, than prevention, especially for backend software.

      For comments, I’m not a fan of inline comments. The “why” comments, especially at module/class level, I am definitely for. I really like how you put it: for deep classes, comments can probably explain a lot of their depth, helping maintenance greatly. Until I read your comment here, I did not think along this dimension, though. Thanks!

    2. 5

      I will be fighting the “no comments” brigade with my dying breath. I don’t think I’m some sort of “rockstar” or “10x code god”, but I’ve been doing this a long time. If I need comments to help read my own damned code six months from now, they’re definitely going to help when somebody else completely needs to work on it.

      1. 5

        I read this book a few months ago, and like Mr. Orosz I felt like it was pretty good but kind of a mixed bag.

        The distinction he makes been tactical and strategic programming is a fantastic point, and probably my #1 takeaway. Shallow vs deep modules is also a great metaphor that I apply in my career.

        I think my biggest disagreement, or shall we say eyebrow raise, was the juxtaposition of his opinion on comments and unit tests.

        Comments provide the only good way to fully capture abstractions, and good abstractions are fundamental to good system design. If you write comments describing the abstractions at the beginning, you can review and tune them before writing implementation code. To write a good comment, you must identify the essence of a variable or piece of code: what are the most important aspects of this thing?

        – Section 15.3 p. 131

        Now, compare that to:

        Although I am a strong advocate of unit testing, I am not a fan of test-driven development. The problem with test-driven development is that it focuses attention on getting specific features working, rather than finding the best design.

        – Section 19.4 pg. 155

        Wow do I disagree with that.

        Now, I’m not dogmatic about TDD. Sometimes you just have to prototype things without tests when you’re finding the design. But TDD helps me think about interfaces from the outside in exactly the same way he talks about the benefits of comments.

        IMO, comments are less helpful than unit tests for this because they always drift out of sync with the code, because you usually don’t have a system to ensure their correctness. (Yes, Go is a notable exception)

        He addresses this last concern this way:

        Comments do sometimes get out of date, but this need not be a major problem in practice. Keeping documentation up-to-date does not require an enormous effort.

        Section 12.3 pg. 98

        LMAO. Okay dude. I don’t even know how to respond to this.

        1. 3

          Thanks for finding the examples. Yes, it seems both you and me have similar views on tests/comments. Most of my experience/pushback on too many comments comes from having seen them become out of date and confusing. I do see, how e.g. for an intro into software design course, this might not come up. But like you, I’d be very-very hesitant on choosing comments over tests, for maintenance.

          1. 4

            I think both are valuable, and on balance I think a codebase with appropriate comments is better than one without.

            But if I had to choose between unit tests and comments, I’d pick unit tests without hesitation.

        2. 3

          Regarding comments, I would recommend a look at the comments in Tcl’s C source code, which follow on the practice established by Ousterhout. That code is some of the most readable C I’ve ever seen.


          1. 2

            That is quite beautiful.

          2. 3

            Cool article! Agree with the fact that we shouldn’t try to handle edges cases during the conception of a piece of software..

            1. 2

              Nice review. I definitely recommend the book, regardless of how much experience you have. It’s well-written and a super short read.

              My favorite chapter was “better together or better apart?”, where he discusses whether or not splitting functions and modules up into smaller units is a good idea, something he criticizes modern software development for overdoing.