Application Programming Interface (API) design is hard. But it's even harder to change once you get it wrong. So what you should do is to spend the effort to get it right the first time around.
In the Linux Kernel community Rusty Russell came up with a API rating scheme to help us determine if our API is sensible, or not. It's a rating from -10 to 10, where 10 is perfect is -10 is hell. Unfortunately there are too many examples at the wrong end of the scale.
| <body onload=z=c.getContext`2d`,setInterval(`c.width=W=150,Y<W&&P<Y&Y<P+E|9<p?z.fillText(S++${Y=`,9,9|z.fillRect(p`}*0,Y-=--M${Y+Y},P+E,9,W),P))):p=M=Y=S=6,p=p-6||(P=S%E,W)`,E=49) onclick=M=9><canvas id=c> |
This is a compiled list of falsehoods programmers tend to believe about working with time.
Don't re-invent a date time library yourself. If you think you understand everything about time, you're probably doing it wrong.
| Convention | Example | General Meaning |
|---|---|---|
to_*() |
str::to_string() |
A conversion from one type to another that may have an allocation or computation cost. Usually a Borrowed type to Owned type. |
as_*() |
String::as_str() |
Convert an Owned type into a Borrowed type. It is usually cheap (maybe even zero-cost) to use this function. |
into_*() |
String::into_bytes() |
Consume a type T and convert it into an Owned type U. |
from_*() |
SocketAddr::from_str() |
Create an Owned type from an Owned or Borrowed type. |
*_mut() |
str::split_at_mut() |
Denotes a mutable reference. |
try_*() |
usize::try_from() |
Method will return a Result or Option type. Usually Result. |
with_*() |
Vec::with_capacity() |
A constructor that has one or more parameters used to configure the type. |
| // Based on a presentation by the immortal Jim Weirich: | |
| // http://vimeo.com/45140590 | |
| // | |
| // clang++ -o ycomb -std=c++1y ycomb.cpp && ./ycomb | |
| #include <functional> | |
| #include <iostream> | |
| using T = int; | |
| using F = std::function<T (T)>; |
