Designing APIs That Don't Lie

There's a particular kind of pain that comes from inheriting an API where the documentation says one thing, the code does another, and the consumers have long since written their own internal notes to track the difference. You stop trusting the spec. You start reading the source directly. The documentation becomes decorative.