Hacker News Reader

Comment by kybernetikos | Hacker News Reader

The advice in 'Replace What Comments With Names' section was just talked about recently here: https://news.ycombinator.com/item?id=37517329 in an article I agree with 'Linear Code Is More Readable'.

If you're going to reuse those little tiny functionettes, then sure, it might be worth doing, but to do it for readability is misguided. Comments are a perfectly reasonable way of indicating logical blocks within code.

View on HN

I've also used scopes for this:

  func DownloadAndVerifyThing(path string) error {
      var url string
      { // Build URL
         ...
         url = [..]
      }
  
      { // Fetch
          ...
      }
  
      { // Verify file.
          ...
      }
  }

I don't do this very often (and I'm having trouble locating an example off-hand, although I'm sure there must be a few in my public code), but it can be pretty useful at times.

I have and do use this for my 'normal' code, but not very often. I tend to prefer breaking things up into functions (usually named, not lambdas). Where I do use this style extensively is in self-testing code:

    // set up data to be tested
    var fred = ...
    var cathy = ...

    { // check fred does something correctly
        var result = fred.reproduce(2);
        assert(result.length() == 2, "fred should have 2 children");
    }

This prevents variable result from escaping and contaminating the next test, which happened an awful lot before I started doing this.

Then maybe better ways; suggestions welcome.

Both _awesome_ comments, I made a similar one up above, but hadn't considered the `testing` use case which is actually really really cool to "protect" your test scope like that. Almost like a fake "setup/teardown".

A different pattern I like in Ruby is the assignment with begin...end:

    fred = begin
      user_finder = ...
      user_finder.find('fred')
    end

Again, not always "self-documenting" as whipping out a new function, but useful if you need to separate chunks and keep the code linear.

The only issue with Ruby itself is that the scope is not lexical, so you can still use `user_finder` outside the block above (linters can catch it, though). But it's still worth to separate code without having a brand new method.

> Comments are a perfectly reasonable way of indicating logical blocks within code.

Comments like these very often end up lying to my face and make me lose precious time. I nowadays tend to semi-ignore them and just read the code anyway. YMMV, I guess.

If you consistently break functions down into tiny “functionettes” the names of the functions can as easily lie to you. You start with `buildURL` but it gets complicated, you break part out into validating the URL, now it should be `buildAndValidateURL` but it’s never updated and the function name “lies”.

I suppose if you prefer to ignore comments, they are more likely to get out of date, which may be why your mileage varies.

Doesn't even have to be an intentional lie. Sometimes there are just multiple "things" a function could be known as and only one can be chosen for the function name. I recently wrote a function crc() that goes and computes the thing. The comments above it talk about what CRC it is (non-obvious without domain knowledge of CRCs and the different forms polynomials can be written in) and why it was chosen. This commonly done with cryptography as well. AES functions are commonly named rijndael with a comment about the standard or vice versa.

Indeed I agree that it can be difficult or impossible to squeeze all the important information about a function into its signature! And why bother playing golf when that’s literally what the doc string is for?

(Obviously you should endeavor to write good names anyway).

No more often than the names of the sub-functions themselves becoming inaccurate ime.

At some point the system does depend on its authors doing the right thing.

The right thing, I can define with code and check for correctness with tests. I guess I mean that if it can be expressed clearly in code, it should.

But I don't completely disagree that they can have their place. They just get used as crutches for unreadable code a lot of time, that's all.

Reply on news.ycombinator.com