Hacker News Reader

Hacker News

Comment by r0s | Hacker News Reader

Full thread

r0s

The purpose of code is for humans to read.

Until AI is compiling straight to machine language, code needs to be readable.

View on HN

Variable names don’t matter in small scopes.

The scope of the cognitive effort is the total context of the system. Yes it matters.

It certainly can matter in any scope. `x` or even `delay` will lead to more bugs down the line than `delay_in_milliseconds`. It can be incredibly frustrating to debug why `delay = 1` does not appear to lead to a delay if your first impression is that `delay` (or `x`) is in seconds.

You will have exactly the same problem if delay_in_milliseconds is actually misnamed and the delay is measured in seconds.

Comments lie. Names lie. Code is the only source of truth.

No - "delay_in_milliseconds" will let you find the error and resolve it faster. With the less descriptive name, you need to notice the mismatch between the definition and the use site, which are further apart in context. Imagine you see in your debugger: "delay_in_milliseconds: 3" in your HttpTimeout - you'll instantly know that's wrong.

If you believe your reductive argument, your function and variable names would all be minimally descriptive, right?

For your specific example, there would never be a “delay in milliseconds” variable in the first place. That’s just throat clearing.

“sleep 1” is the complete expression. Because sleep takes a parameter measured in seconds, it’s already understood.

You do not need “delay_in_seconds = 1” and then a separate “sleep delay_in_seconds”. That accomplishes nothing, you might as well add a comment like “//seconds” if you want some kind of clarity.

Years later, when all memory of intent is long gone, I'd much rather work on a large code base that errs on the side of too much "throat clearing" than one that errs on the side too little. `sleep 1` tells what was written, which may or may not match intent.

Many bugs come from writing something that does not match intent. For example, someone writes most of their code in another language where `sleep` takes milliseconds, they meant to check the docs when they wrote it in this language, but the alarm for the annual fire drill went off just as they were about to check. So it went in as `sleep 1000` in a branch of the code that only runs occasionally. Years later, did they really mean 16 minutes and 40 seconds, or did they mean 1 second?

Leaving clues about intent helps detect such issues in review and helps debug the problems that slip through review. Comments are better than nothing, but they are easier to ignore than variable names.

If the code isn’t working, then intent doesn’t matter. The code was wrong.

If the code is working, the intent also doesn’t matter, what was written is what was intended.

Do the requirements call for an alarm of 16 minutes 40 seconds? Then leave the code be. If not, just change it.

The only correct way is

    delay = Duration.milliseconds(1)

Reply on news.ycombinator.com