Live data from Hacker News

Comments on Comments

noncombatant.org

31–40 of 50 posts

Re: Comments on Comments

#31
An interesting go-ish thing to do regarding: """Now, DownloadAndVerifyThing is shorter, contains less state, and is more obviously a composition of several tasks."""

...I've experimented with "convert a long sequential, independent function into several internal anonymous functions" (ie: similar to IIFE in javascript).

This generally prevents (or contains) variable leakage and prevents (or contains) "complexity leakage".

In their example: `DownloadAndVerifyThing(...) { ... }`, those functions could be defined internal to the `DownloadAndVerifyThing` function, which is kindof a further form of comment: "thou shalt not be using these weird functions outside of this particular function which does the downloading and verifying..."

Even if it's done not in a function but in an anonymous block, "trapping" any state leakage or side-effects is nice for complexity reduction.

Example:

    func Foo() bar {
        {
            x := 1
            y := 2
            ...lots of math, etc...
        }
        abc := 123
    }
...you're not polluting the function internally with a lot of extra variables hanging around, which makes the inevitable refactoring "more clean" as you know at least the code block can be extracted independently w/o impacting anything _after_ it (although you still have to be a little careful with the "before" and "ordering" portion of it).

Re: Comments on Comments

#32
post #10

In the “Why” vein, some of the most important comments are “Why I made the compromises I made” aka “Why this looks dumb but is actually for the best” comments. They can prevent someone, including myself, from undergoing a timely rewrite of strange or bad looking code before inevitably hitting the same wall I hit previously.

...and the epic "comment the empty `else`-block":

   ... } else { /* no action needed, enterprise users should not frib or frob... */ }

Re: Comments on Comments

#33
post #27

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.

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.

Re: Comments on Comments

#34
post #22
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…

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

Re: Comments on Comments

#35

The fundamental issue with comments in programming is that they're part of the code, which is a ridiculous hack that somehow survives unquestioned. This is not how comments work in Google Docs, Microsoft Word, etc.. Maybe the idea of implementing comments as a greyed out part of the main text did not occur to the designers of these apps?

The is not the natural state of things. That's also not the original state of things.

For the decades that software engineering has existed, people have been busy migrating more and more information from offline in a different context into inline right at the code. Every single one of those times, people have experienced huge gains on the quality of the resulting comments, with moderate gains on project organization and productivity.

So, the reason comments are a greyed text inline with the code is that it has worked better. Having the comments offline (like software used to have) is very likely a flaw of those platforms. But well, the text-creation people never looked at improving their tooling anyway.

Re: Comments on Comments

#36
post #27

Earlier quoted context omitted.

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

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.

Re: Comments on Comments

#37

Earlier quoted context omitted.

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

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…

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

Re: Comments on Comments

#38
You all would hate my code, and that's okay. Why? Because I do everything that is suggested, save one: I leave what comments in.

For some reason, it is easier and quicker for me to understand English prose than code, even if the code is simple. That includes checking the actual code after reading the comment to see if it matches; having a target for the code makes it orders of magnitude easier to read for me.

That said, I still weirdly find value in what comments. Even some of the simplest ones communicate intent for me.

For example, I have many comments that take one of the following forms:

    // Cache this.
    // Get the .
These are the exact comments that people hate so much, but I like them because they communicate these things to me:

* The item is gotten for efficiency reasons. This means that I should check that it really is more efficient if something is slow.

* More importantly, the item is expected to not change, so if I'm digging aground for a bug, I should check that the item actually does not change.

So these "useless" comments actually help me.

In addition, the fear that they will go out-of-date is less of a problem for me because I have a strict habit of updating comments with code.

Now, I don't suggest that everybody do what I do; I suggest the opposite, in fact. But I work alone, so I can do things that were ideal for myself.

Re: Comments on Comments

#39
post #30
post #27

Earlier quoted context omitted.

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

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.

Re: Comments on Comments

#40

The fundamental issue with comments in programming is that they're part of the code, which is a ridiculous hack that somehow survives unquestioned. This is not how comments work in Google Docs, Microsoft Word, etc.. Maybe the idea of implementing comments as a greyed out part of the main text did not occur to the designers of these apps?

The is not the natural state of things. That's also not the original state of things. For the decades that software engineering has existed, people have been busy migrating more and more information from offline in a different context into inline right at the code. Every single one of those times, people have experienced huge gains on the quality of the resulting comments, with moderate gains on project organization…

Different context meaning random chats and mailing lists, not an integrated system like Google Docs or Microsoft Word.
Post reply on HN