Clean Code book has some good guidelines but sometimes becomes too fanatical for my taste. For example, comments in good doses are really good.

And people sho accept it as Gospel are making a mistake.

  • 1
    Well, comments should be there if you are writing code not understandable at first glance, or if you need to give a reason. And the book clearly states that.
  • 2
    Did it ever mention the term "self-documenting"?
  • 3
    I also like it when there's some calculation of let's say 10 lines to put a comment what this block will be about. Of course I could also see it from what's being done there, but it's faster to scan one line than ten.

    And no, I hate it when everything is broken into super small functions that aren't actually being reused anywhere, except when it's something thematically really enclosed.
  • 3
    @Fast-Nop another thing that bugged me. Moar functions moooaaarrrr.
  • 1
    @Fast-Nop functions are not completely just for reuse but for description, if used correctly comments are built into the function names so the top function reads like a story and there is no need for comments anymore
  • 1
    @Minion Yeah, and you have to jump back and forth in the source text to see what's actually going on. Now I don't avow making functions thousands of lines and using block comments instead of functions, but splitting everything into functions with a handful of lines sucks equally.
  • 2
    @Fast-Nop Can only agree. Cutting everything in such small pieces that you have to solve a jigsaw to understand the code, is the opposite of clean.
  • 1
    @Fast-Nop make those functions based on SRP with descriptive names and I don't see why would you still need jumping back and forth. Srp detaches helpers/funstions from it's client logic and a descriptive name summarizes what that fn does. So you'd know what's happening while only reading the caller fn
  • 1
    @netikras Yeah that works for simple result computation or getters/setters. It doesn't work for functions with actual logic when you're reading the source to figure out what exactly is going on.

    Escpecially when you're trying to fix a bug that you can't even reproduce.
  • 0
    @Fast-Nop the point of <10loc fn is to make all algorithms simple :) simple to read at least -- not simple to execute. Divide the complex calculations into simple steps. Divide et impera.
  • 1
    @netikras And sure, if I have some functionality that is an enclosed logic block in itself, then I make it a function even if it isn't being reused. Like computing a CRC-32 over a given memory block.
  • 4
    @netikras I don't think it makes it simple if I have to piece everything together like in a puzzle. It's the opposite of readable. When I encounter something like that and have the opportunity, I eliminate this stuff and combine it if the only reason is "make everything short" and not "this is a logic piece of its own".
  • 1
    @netikras please don't use the acronym on things that are the last in a list of 15 in our field alone.

    @Fast-Nop when debugging lots of tiny functions can be annoying. If they are in sequence and the main routine is just call after call it does tell the narrative and help you pinpoint the problem area in most cases. In the other cases yeah you read twice as much and jump around to make sense of it.

    Make shit short just because you can is always stupid.
Add Comment