Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Comments on Comments

noncombatant.org

Post reply on HN
Print view View original

21–30 of 50 posts

Re: Comments on Comments

#22

Post by _a_a_a_ »

arp242 wrote: post #12
kybernetikos wrote: post #6

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.

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.

Re: Comments on Comments

#23

Post by ranting-moth »

cjfd wrote: post #14
ranting-moth wrote: post #4

Code is logic. Comments are wisdom.

I have seen many comments that are the opposite of wisdom.

I have to agree. Even in some cases wisdom went into hiding and applied for witness protection when he saw what was being written.

But I think it's a good phrase to keep in mind when writing comments.

Re: Comments on Comments

#24

Post by whstl »

_a_a_a_ wrote: post #22
arp242 wrote: post #12

Earlier quoted context omitted.

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 va…

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.

Re: Comments on Comments

#25

Post by ranting-moth »

mannykannot wrote: post #21
cjfd wrote: post #14

Earlier quoted context omitted.

I have seen many comments that are the opposite of wisdom.

Indeed, and I have also seen much code which does not do what is alleged by the names given to its identifiers.

And sometimes it severely lacking. I heard of this 5000 line "onClick()" function where most of the program, screaming and yelling, had been forcefully stuffed.

Re: Comments on Comments

#26

Post by crznp »

hitchstory wrote: post #2

100% agree with most of this, but I think the why can be dug into a little deeper. Under why comments I find they fit into two categories: 1) Why does the code exhibit behavior X? (~80%) 2) Why does the code do X this way? (~20%) 1 is usually a customer facing quirk which should be written down somewhere, but preferably not in the code directly. This stuff fits extremely well in tests which exercise the behavior ("wh…

For (1), anything outside of the code is going to be missed in the next code review. Eg:

// ACME-1275 Acme uses desc field to identify references

Perhaps you can use the reference to point to wherever you documented it. I'd rather just keep the ticket reference, which won't change. Who wants to read docs that get into that kind of minutia anyway?

But without any comment, I'm wasting time looking for it, if I even realize that there is something to be looked up.

Re: Comments on Comments

#27

Post by folkrav »

kybernetikos wrote: post #6

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.

> 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.

Re: Comments on Comments

#28

Post by adzm »

Tangential but I will say that c# is a great multi-paradigm language with terrible code comment culture that still uses xml-based comments, ugh it drives me crazy. I've even looked into figuring out how to get the compiler to auto transform javadoc-style or implicit-style comments into the structured format it expects, but it's been tricky. I find this verbosity with the xml markup makes it more difficult to read as a human and discourages good comments.

Re: Comments on Comments

#30

Post by jonahx »

folkrav wrote: post #27
kybernetikos wrote: post #6

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.

> 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.

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.

Post reply on HN