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.

▲

fwip 3 days ago | parent [-]

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?

▲

deadbabe 3 days ago | parent [-]

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.

▲

rented_mule 3 days ago | parent [-]

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.

	▲	deadbabe 3 days ago \| parent [-]
		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.