api-guidelines
api-guidelines copied to clipboard
Extend best-practice list: recommend using typed units instead of integer-based conversions
It would be nice to recommend using typed units of measurement whenever possible.
E.g. in our official libraries we gave up on API in the form of foo(timeMillis: Long)
and foo(time: Long, unit: TimeUnit)
-- it's unnecessarily verbose, unclear from the call site (esp. when callers do not follow the naming convention), and, most importantly, is error-prone (off-by-order-of-magnitude errors). AFAIR Google even used to have a JVMLS talk about that, but all I can find is this discussion.
The same applies to any "easily-convertible" units -- SI, durations, bytes (kilo-/mega-) etc.