What makes a good standard library?

  • It should be consistent in its use of idioms in order to reduce the number of lookups required. Still, it should be documented extraordinarily well, because it then can serve as an on-ramp to best practices for novices. Further, it should be tailored to the intended use case of the language to stay lean but usable to carry an application as far as possible without needing a heap of dependencies.

    I appreciate these qualities in the standard library of Crystal [1], to name an example.

    [1] https://crystal-lang.org/api/1.7.0/

  • * Predictability and convention are more important than totally clean design. Over the course of a language lifetime, code style best practice is going to change so you almost certainly won't have uniform interfaces. Your Clojure example of functions passing the input as first vs last is actually an example of this -- functions that work on sequences expect the last arg, and functions that work on datastructures expect the first arg. It's an official convention, check out different uses of the -> and ->> macros and you'll always see it.

    * Some form of discoverability. Ideally there'd be good docs available explaining the behaviour of the library in human friendly language, with multiple code examples. Bonus points for making the library open source and linking directly to the implementation from documentation.

    * No breaking changes. It's better to create a new library than try and shoehorn a significantly different release into semantic versioning for the sake of it.

    * "Escape hatches" for effectful functions to override default behaviour. For example, a HTTP client library isn't going to be very useful if you can't override pretty much any configuration property.

    * Being explicit about any side effects resulting from the code, either in naming or by documentation.

  • Something I really like about Scheme is how mutators are generally suffixed with an exclamation point and predicates with a question mark. For example:

      (null? spotted-ufos)
      (vector-set! drakes 0 maui-mallard)
    
    Having a simple and clear convention like that is something I consider good design.