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

Maybe comments should explain 'what' (2017)

hillelwayne.com

Post reply on HN
Print view View original

191–200 of 212 posts

Re: Maybe comments should explain 'what' (2017)

#191

Post by scoofy »

zahlman wrote: post #188
scoofy wrote: post #184

Earlier quoted context omitted.

Lists are mutable, tuples are not… that’s a massive difference if I’m editing code deep in a function I wrote two years ago.

The point is that you clearly aren't mutating it in the current context . Therefore, knowing that you could mutate it doesn't help you understand what the current code is doing, nor guide you away from mistakes (as you would have no reason to try to mutate it).

I operate a site where I have lists of things that have operations done on them all the time, occasionally I’ll load those series into memory as a tuple to save memory.

If I’m adding a feature to the site in 5 years, it’s going to be important to know if I’ve done that or not.

Re: Maybe comments should explain 'what' (2017)

#193

Post by bluecalm »

zahlman wrote: post #177
bluecalm wrote: post #134

Earlier quoted context omitted.

It's like with goto. Goto is useful and readable in quite a few situations but people will write arrow like if/else tree with 8 levels of indentation just to avoid it because someone somewhere said goto is evil.

Funny how my Python code doesn't have those arrow issues. In C code, I understand some standard idioms, but I haven't really ever seen a goto I liked. (Those few people who are trying to outsmart the compiler would make a better impression on me by just showing the assembly.) IMX, people mainly defend goto in C because of memory management and other forms of resource-acquisition/cleanup problems. But really it comes…

You're assuming function calls or other constructs are more readable and better programming. I don't agree. Having a clear clean-up or common return block is a good readable pattern that puts all the logic right there in one place.

Jumping out of the loop with a goto is also more readable than what Python has to offer. Refactoring things into functions just because you need to control the flow of the program is an anti pattern. Those functions add indirection and might never be reused. Why would you do that even if it was free performance wise?

This is why new low level languages offer alternatives to goto (defer, labelled break/continue, labelled switch/case) that cover most of the use cases.

Imo it's debatable if those are better and more readable than goto. Defer might be. Labelled break probably isn't although it doesn't matter that much.

Python meanwhile offers you adding more indirection, exceptions (wtf?) or flags (inefficient unrolling and additional noise instead of just goto ITEM_FOUND or something).

Re: Maybe comments should explain 'what' (2017)

#194

Post by kmoser »

peheje wrote: post #130
tetha wrote: post #50

Earlier quoted context omitted.

> That's explaining "what" but also implicitly "why" - because that's how double-entry works and that's the tolerance banks allow for settlement delays. You can't really extract that into a method name without it becoming absurd. That's why I've also started to explicitly decompose constants if possible. Something like `ageAlertThresholdHours = backupIntervalHours + approxBackupDurationHours + wiggleRoomHours`. Sure,…

I don't necessarily disagree with providing context, but my concern is that comments eventually lie. If the business rule evolves (say the window moves to 5 days) the comment becomes a liability the moment someone updates the code but forgets the prose. The comment also leaves me with more questions: how do you handle multiple identical amounts in that window? I would still have to read the implementation to be sure.…

> I don't necessarily disagree with providing context, but my concern is that comments eventually lie. If the business rule evolves (say the window moves to 5 days) the comment becomes a liability the moment someone updates the code but forgets the prose.

Yes, comments can drift out of sync with the code. That doesn't mean the comments were a bad idea; it just means the programmer didn't update the comments when they should have.

Similarly, even with zero comments, variable names can drift out of sync with their intended purpose, e.g. when they are repurposed to hold values that are different from what their name implies. Again, the solution is to rename the variable so it reflects its purpose (or possibly create another variable).

> This way, the 3 day rule is a hard requirement that fails the build if broken rather than a suggestion in a comment block.

What happens when a dev changes the test code, but fails to update the string "should_match_debit_with_credit_only_if_within_three_day_settlement_window"? That's effectively no different than comments being out of sync with the code.

Re: Maybe comments should explain 'what' (2017)

#195

Post by Scarblac »

zahlman wrote: post #178
Scarblac wrote: post #136

Earlier quoted context omitted.

A colleague recently added a linter rule against nested ternary statements. OK, I can see how those can be confusing, and there's probably a reason why that rule is an option. Then replaced a pretty simple one with an anonymous immediately invoked function that contained a switch statement with a return for each case. Um, can I have a linter rule against that?

I guess "anonymous IIFE" is the part that bothers you. If someone is nesting ternary expressions in order to distinguish three or more cases, I think the switch is generally going to be clearer. Writing `foo = ...` in each case, while it might seem redundant, is not really any worse than writing `return ...` in each case, sure. But I might very well use an explicit, separately written function if there's something ob…

It just looked way more complex (and it's easy to miss the () at the end of the whole expression that makes it II). And the point of the rule was to make code more readable.

Basically it's a shame that Typescript doesn't have a switch-style construct that is an expression.

And that nowadays you can't make nested ternaries look obvious with formatting because automated formatters (that are great) undo it.

Re: Maybe comments should explain 'what' (2017)

#196

Post by 1718627440 »

BoorishBears wrote: post #143
1718627440 wrote: post #89

Earlier quoted context omitted.

As for the comments, I would probably write it like this: /* Symbol actually exists */ if ((NULL != getSymbol (symbolName) /* and still to be added */ && (!alreadyReplaced.contains (symbolName)) { ... Although in this specific case the comments seem like noise to me. > Technically this performs worse because you lose short-circuiting Not really, because optimizing compilers are a thing, when this thing is parsed into…

The compiler would have to determine that these are pure calls which I wouldn't rely on if performance actually matters I just tested a recent gcc at -O2 with a contrived example using strings in an unordered_set: a look-up always occurs if not relying on short-circuiting

True, I missed that the calls likely traverse translation units, because this is not how I write code.

Re: Maybe comments should explain 'what' (2017)

#197

Post by epgui »

lukan wrote: post #158
epgui wrote: post #155

Earlier quoted context omitted.

I almost (?) always advise against “what” comments. I have rarely (if ever?) encountered any cases where “what” comments didn’t have a better (and practical/cheap/easy enough) solution. In my experience, when I review junior contributors’ code and see “what” comments, it’s usually caused by 1) bad naming, or 2) abstractions that don’t make sense, or 3) someone trying to reinvent maths but incorrectly, or 4) missing t…

For sure, bad code exists. But if I have to work with bad unclear code, "what" comments are very helpful. Like something really bad x=y //triggers method xyz So I would agree that under controlled conditions, they should not be necessary.

Two words: referential transparency

Re: Maybe comments should explain 'what' (2017)

#198

Post by rossant »

matt_kantor wrote: post #90
rossant wrote: post #45

I like to use comments extensively, even if it’s just to visually separate blocks of code in my IDE. A bit more spacing simply feels cleaner to me.

Why not use blank lines? (I suspect the answer might be "my code formatter deletes them", which is a damn shame.)

I do it, but I also like to use headers.

Re: Maybe comments should explain 'what' (2017)

#199

Post by ryandv »

Comments exist to provide information beyond primitive, domain-agnostic types (String, Int, etc.), but without the overhead of more elaborate modelling into domain-specific types (ChequingAccounts, Widgets, and so forth).

I may want to communicate further information about the inhabitants or values of a particular type, without introducing extraneous or superfluous types:

    -- given a path to a PEM encoded PKCS#8 formatted RSA private key and a
    -- JWT Claims Set (RFC 7519) represented as a strict ByteString,
    -- return a strict ByteString representing a base64 encoded RSA256-signed JWS.
    generateJWT :: FilePath -> B.ByteString -> IO (Maybe B.ByteString)
    generateJWT fp claims = (fmap unJwt ) . (maybe (return Nothing) (fmap eitherToMaybe . encodeClaims) =
Arguably newtype wrappers could (or even should) be introduced in place of the more primitive FilePaths and ByteStrings - but even if they were, the type names would either be prohibitively long, or fail to communicate the full depth of information of the comment.

Re: Maybe comments should explain 'what' (2017)

#200

Post by tptacek »

jcranmer wrote: post #144
WillAdams wrote: post #71

Earlier quoted context omitted.

For an example of what happens when he runs into a real programmer see: https://github.com/johnousterhout/aposd-vs-clean-code _A Philosophy of Software Design_ is an amazing and under-rated book: https://www.goodreads.com/en/book/show/39996759-a-philosophy... and one which I highly recommend and which markedly improved my code --- the other book made me question my boss's competence when it showed up on his desk, but…

That entire conversation on comments is just wildly insane. Uncle Bob outright admits that he couldn't understand the code he had written when he looked back on it for the discussion, which should be an automatic failure. But he tries to justify the failure as merely the algorithm just being sooooo complex there's no way it can be done simply. (Which, compared to the numerics routines I've been staring out, no, this…

The whole thing is really uncomfortable; it's as if, after attempting the sudoku solver, Ron Jeffries sat down for a discussion with Peter Norvig, who was not especially diplomatic about the outcome of the experiment. The section before that, where they're talking about the "decomposition" of Knuth's simple primality tester, is brutal. "Looping over odd numbers is one concern; determining primality is another".
Post reply on HN