Maybe comments should explain 'what' (2017) • Hacker News Board

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

#181

Post by zahlman » Mon, Jan 05, 2026, 1:07 AM UTC

scoofy wrote: post #163

I feel like a complete weirdo when it comes to comments and variable names. I've never worked professionally as a coder, but I've been working with python and a bit of js for like 15 years now. I strongly believe that variable names should be long, and explain what they are, and that comments should be long, and explain what's happening. I have no idea why people want to "save time" to write short comments and short…

> I have no idea why people want to "save time" to write short comments and short variable names

Really long variable names put extra space between the operators and calls, which makes it harder to grok the logical structure of the expression. When I write `a + b` in code, it's in that order because the language demands it, and I use languages with that syntax for reasons of familiarity; but really, the `+` is the most important thing there, so it shouldn't be buried way off to the right.

I don't like for variable names to mark type. `weight_radius_price` is fine (and usually much better than `wrp`, and definitely much better than `tuple` or `t`) but a) we know it's a 3-tuple because we can see the right-hand-side of the equals sign; b) the structure of the name already conventionally tells us to expect more or less that (although maybe a class or structure abstraction is missing?); c) the choice of a tuple is probably not really relevant in context as compared to other ways of sticking three atomic values together.

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

#182

Post by zahlman » Mon, Jan 05, 2026, 1:10 AM UTC

scoofy wrote: post #179

gavmor wrote: post #169

Earlier quoted context omitted.

"tuple" is entirely redundant with the types, though.

I’m not sure what you mean. You’re not necessarily going to know the type of a variable just by reading a random section of code… especially in Python. I absolutely going to add the type to the variable name if it’s a complex function. It’s just clearer.

The point is to not care about the type. If you see `weight, radius, price = ...`, then it generally isn't going to matter whether `...` is a tuple or a list (or more exotic possibilities). What matters is that you can iterate over it, and iterating over it gives exactly three results, and the first result represents a weight, etc.

If your weights need to be, say, a floating-point number of kilograms, then you establish that convention, and only mark intentional deviations from the convention (e.g. because you're doing an explicit conversion to format output). (Or you use a library like Pint to give more formality to it.)

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

#183

Post by Rapzid » Mon, Jan 05, 2026, 1:13 AM UTC

awesan wrote: post #2

I feel like no one serious uses the uncle Bob style of programming anymore (where each line is extracted into its own method). This was a thing for a while but anyone who's tried to fix bugs in a codebase like that knows exactly what this article is talking about. It's a constant frustration of pressing the "go to definition" key over and over, and going back and forth between separate pieces that run in sequence. I…

The Ruby ecosystem was particularly bad about "DRY"(vs WET) and indirection back in the day.

Things were pretty dire until Sandi Metz introduced Ruby developers to the rest of the programming world with "Practical Object-Oriented Design". I think that helped start a movement away from "clever", "artisanal", and "elegant" and towards more practicality that favors the future programmer.

Does anyone remember debugging Ruby code where lines in stack traces don't exist because the code was dynamically generated at run time to reduce boilerplate? Pepperidge Farm remembers.

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

#184

Post by scoofy » Mon, Jan 05, 2026, 1:32 AM UTC

zahlman wrote: post #182

scoofy wrote: post #179

Earlier quoted context omitted.

I’m not sure what you mean. You’re not necessarily going to know the type of a variable just by reading a random section of code… especially in Python. I absolutely going to add the type to the variable name if it’s a complex function. It’s just clearer.

The point is to not care about the type. If you see `weight, radius, price = ...`, then it generally isn't going to matter whether `...` is a tuple or a list (or more exotic possibilities). What matters is that you can iterate over it, and iterating over it gives exactly three results, and the first result represents a weight, etc. If your weights need to be, say, a floating-point number of kilograms, then you establ…

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.

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

#185

Post by scoofy » Mon, Jan 05, 2026, 1:35 AM UTC

zahlman wrote: post #181

scoofy wrote: post #163

I feel like a complete weirdo when it comes to comments and variable names. I've never worked professionally as a coder, but I've been working with python and a bit of js for like 15 years now. I strongly believe that variable names should be long, and explain what they are, and that comments should be long, and explain what's happening. I have no idea why people want to "save time" to write short comments and short…

> I have no idea why people want to "save time" to write short comments and short variable names Really long variable names put extra space between the operators and calls, which makes it harder to grok the logical structure of the expression. When I write `a + b` in code, it's in that order because the language demands it, and I use languages with that syntax for reasons of familiarity; but really, the `+` is the mo…

> we know it's a 3-tuple because we can see the right-hand-side of the equals sign

In the context I’m referring to, the variable may have been set 80 lines earlier, 7 years ago, when I was worse at coding.

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

#186

Post by nvader » Mon, Jan 05, 2026, 1:39 AM UTC

I will take the bait and selectively flame the use of "f. ex" for "for example", when the standard e.g. is available.

Thought-provoking article, nonetheless!

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

#187

Post by [deleted] » Mon, Jan 05, 2026, 1:51 AM UTC

bluecalm wrote: post #134

Scarblac wrote: post #23

Earlier quoted context omitted.

Turns out writing a book and getting it published with the title "Clean Code" is great marketing. I have had so many discussions about that style where I tried to argue it wasn't actually simpler and the other side just pointed at the book.

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.

[deleted]

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

#188

Post by zahlman » Mon, Jan 05, 2026, 2:20 AM UTC

scoofy wrote: post #184

zahlman wrote: post #182

Earlier quoted context omitted.

The point is to not care about the type. If you see `weight, radius, price = ...`, then it generally isn't going to matter whether `...` is a tuple or a list (or more exotic possibilities). What matters is that you can iterate over it, and iterating over it gives exactly three results, and the first result represents a weight, etc. If your weights need to be, say, a floating-point number of kilograms, then you establ…

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

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

#189

Post by zahlman » Mon, Jan 05, 2026, 2:21 AM UTC

scoofy wrote: post #185

zahlman wrote: post #181

Earlier quoted context omitted.

> I have no idea why people want to "save time" to write short comments and short variable names Really long variable names put extra space between the operators and calls, which makes it harder to grok the logical structure of the expression. When I write `a + b` in code, it's in that order because the language demands it, and I use languages with that syntax for reasons of familiarity; but really, the `+` is the mo…

> we know it's a 3-tuple because we can see the right-hand-side of the equals sign In the context I’m referring to, the variable may have been set 80 lines earlier, 7 years ago, when I was worse at coding.

I mean, good habits tend to compound each other.

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

#190

Post by scoofy » Mon, Jan 05, 2026, 2:41 AM UTC

zahlman wrote: post #189

scoofy wrote: post #185

Earlier quoted context omitted.

> we know it's a 3-tuple because we can see the right-hand-side of the equals sign In the context I’m referring to, the variable may have been set 80 lines earlier, 7 years ago, when I was worse at coding.

I mean, good habits tend to compound each other.

I think this response misses the point. Yes, if I’d not been worse at coding a decade ago, I wouldn’t be revisiting the code in the first place.

The point of the redundancy of very clear, descriptive variable names, is that the code is going to suck tomorrow, even if it is good today. Future me is always going to look down on today me. The difference is that I planing for that, so maybe I can help out future me by being verbose, even if it isn’t necessary for much of the code that ends up being fine.

When I have a nasty bug, I don’t want to waste a day on something that could have been clear if I’d just explained it properly.