5 ms·

One more tip: If you're ever designing an API like this, instead of: time.sleep(300) Put your units in the method name: time.sleep_seconds(300) Likewise, if

One more tip: If you're ever designing an API like this, instead of: time.sleep(300) Put your units in the method name: time.sleep_seconds(300) Likewise, if you're making a .length() method where the units are at all ambiguous (like the length of a string), name your units. Bad: str.len(). Good: str.len_chars() / str.len_utf8_bytes(). (I'm looking at you, Rust!)

xyzzy_plugh 5y ago
The solution to this is as old as salt: typedef int seconds; and time.sleep(seconds duration);
- ameliaquining 5y ago
  That doesn't really seem better, because the fact that the unit is seconds is only obvious if you happen to be looking at the function signature in the header or somesuch. This is because C typedefs are type aliases, not newtypes. If seconds were instead a struct with a single int field, or something like that, then that would help a little. To really solve this problem, you need information hiding, which C doesn't have except through questionable hacks.
adtac 5y ago
I'm sorry, but if a language forced me to write str.len_utf8_bytes() every time I wanted the length of a string, I'd just stop using that language.
- mgdlbp 5y ago
  Though it might encourage some to consider str.len_extended_grapheme_clusters()
- jeffparsons 5y ago
  Out of interest, which length did you want?
  - jhasse 5y ago
    Number of characters
    - int_19h 5y ago
      What's a "character"? A codepoint? A glyph? Is "ﬁ" a single character? How about "ß"? "Ȣ"? "Ĳ"? When programmers get answers to these questions wrong, the code that they write ends up being broken for someone out there. And they do get it wrong if their native culture instills a wrong kind of "common sense" about scripts. Which is precisely why we need more stuff like str.len_utf8_bytes() - because it forces the person writing it to consider their assumptions.
      - josephg 5y ago
        Yep. I think about this stuff a lot and I still mess this up all the time. I’ve come to realise that string.length in javascript is a footgun. Basically every time I use it, my code is wrong when I test with non-ascii characters. I’ve spent the last decade writing javascript and I’ve never once actually cared to know what half the UTF16 byte length of a string is. The only legitimate uses are internal in javascript (since other parts of JS make that quantity meaningful). Like using it in slice() or iterating - though for the latter we now have Unicode string iteration anyway.
      - jhasse 5y ago
        > Is "ﬁ" a single character? [...] "Ȣ"? "Ĳ"? I don't know these, someone who does could properly tell you. The implementation could fallback to "glyph" or "codepoint" (don't know what those are exactly) if it is unsure. Mostly right is better than nearly always wrong (= returning number of bytes) IMHO. > How about "ß"? That's one character. > When programmers get answers to these questions wrong, the code that they write ends up being broken for someone out there. So? Returning the number of bytes would also be wrong. Renaming len to len_glyphs will just result in most programmers typing more and some accidentally using len_utf8_bytes (returns the number of bytes?) where len_glyphs would be less wrong.
  - deleted 5y ago
    [deleted]
rahimiali 5y ago
time.sleep_seconds is appealing, but this approach doesn't work when a function takes additional arguments. for example, if your function is poll_file_descriptors(read_descriptors, write_desciptors, timeout_in_seconds) it would be awkward to change the name of the function just because on of the arguments happens to refer to time.
- joshvm 5y ago
  I would always make a local variable for things like this, to avoid magic numbers (especially if a function signature has several numeric arguments). Then you can explicitly put the units in the variable name, e.g. duration_s = 300 and pass that. It's fine if the signature tells you the units, but it doesn't help anyone reading the code if you have poll_file_descriptors(read_descriptors, write_desciptors, 300).
  - mulmen 5y ago
    But how do you know the unit to use in the variable?
    - Karellen 5y ago
      You have to read the documentation. But you need to do that in order to be able to use the API properly anyway. The point the article is making is not about making it easier to write a line of code, but about making it easier to read a line of code. Given that most lines of code are read many more times than they are written, this is a good thing to focus on. "Programs must be written for people to read, and only incidentally for machines to execute." ― Abel and Sussman, Structure and Interpretation of Computer Programs, 1984
      - josephg 5y ago
        Being forced to read the documentation carefully every time you call the method is really bad UX though. And the approach in the article (let ms = 5; sleep(ms);) can be wrong. Maybe the method is actually taking microseconds not milliseconds and this causes a bug. I can also imagine linters (or other humans) fighting this style, since it’s longer, and something you have to actively do every time you call the method. Putting the units in the method name (when you can) fixes all of this. Sleep_milliseconds(5) is impossible to misuse or leave undocumented.

xyzzy_plugh 5y ago

The solution to this is as old as salt: typedef int seconds; and time.sleep(seconds duration);

ameliaquining 5y ago
That doesn't really seem better, because the fact that the unit is seconds is only obvious if you happen to be looking at the function signature in the header or somesuch. This is because C typedefs are type aliases, not newtypes. If seconds were instead a struct with a single int field, or something like that, then that would help a little. To really solve this problem, you need information hiding, which C doesn't have except through questionable hacks.

adtac 5y ago

I'm sorry, but if a language forced me to write str.len_utf8_bytes() every time I wanted the length of a string, I'd just stop using that language.

mgdlbp 5y ago
Though it might encourage some to consider str.len_extended_grapheme_clusters()
jeffparsons 5y ago
Out of interest, which length did you want?
- jhasse 5y ago
  Number of characters
  - int_19h 5y ago
    What's a "character"? A codepoint? A glyph? Is "ﬁ" a single character? How about "ß"? "Ȣ"? "Ĳ"? When programmers get answers to these questions wrong, the code that they write ends up being broken for someone out there. And they do get it wrong if their native culture instills a wrong kind of "common sense" about scripts. Which is precisely why we need more stuff like str.len_utf8_bytes() - because it forces the person writing it to consider their assumptions.
    - josephg 5y ago
      Yep. I think about this stuff a lot and I still mess this up all the time. I’ve come to realise that string.length in javascript is a footgun. Basically every time I use it, my code is wrong when I test with non-ascii characters. I’ve spent the last decade writing javascript and I’ve never once actually cared to know what half the UTF16 byte length of a string is. The only legitimate uses are internal in javascript (since other parts of JS make that quantity meaningful). Like using it in slice() or iterating - though for the latter we now have Unicode string iteration anyway.
    - jhasse 5y ago
      > Is "ﬁ" a single character? [...] "Ȣ"? "Ĳ"? I don't know these, someone who does could properly tell you. The implementation could fallback to "glyph" or "codepoint" (don't know what those are exactly) if it is unsure. Mostly right is better than nearly always wrong (= returning number of bytes) IMHO. > How about "ß"? That's one character. > When programmers get answers to these questions wrong, the code that they write ends up being broken for someone out there. So? Returning the number of bytes would also be wrong. Renaming len to len_glyphs will just result in most programmers typing more and some accidentally using len_utf8_bytes (returns the number of bytes?) where len_glyphs would be less wrong.
- deleted 5y ago
  [deleted]

rahimiali 5y ago

time.sleep_seconds is appealing, but this approach doesn't work when a function takes additional arguments. for example, if your function is poll_file_descriptors(read_descriptors, write_desciptors, timeout_in_seconds) it would be awkward to change the name of the function just because on of the arguments happens to refer to time.

joshvm 5y ago
I would always make a local variable for things like this, to avoid magic numbers (especially if a function signature has several numeric arguments). Then you can explicitly put the units in the variable name, e.g. duration_s = 300 and pass that. It's fine if the signature tells you the units, but it doesn't help anyone reading the code if you have poll_file_descriptors(read_descriptors, write_desciptors, 300).
- mulmen 5y ago
  But how do you know the unit to use in the variable?
  - Karellen 5y ago
    You have to read the documentation. But you need to do that in order to be able to use the API properly anyway. The point the article is making is not about making it easier to write a line of code, but about making it easier to read a line of code. Given that most lines of code are read many more times than they are written, this is a good thing to focus on. "Programs must be written for people to read, and only incidentally for machines to execute." ― Abel and Sussman, Structure and Interpretation of Computer Programs, 1984
    - josephg 5y ago
      Being forced to read the documentation carefully every time you call the method is really bad UX though. And the approach in the article (let ms = 5; sleep(ms);) can be wrong. Maybe the method is actually taking microseconds not milliseconds and this causes a bug. I can also imagine linters (or other humans) fighting this style, since it’s longer, and something you have to actively do every time you call the method. Putting the units in the method name (when you can) fixes all of this. Sleep_milliseconds(5) is impossible to misuse or leave undocumented.