On Wednesday 18 May 2005 11:58, Graham Klyne wrote:
So I ask myself: are there any good papers or books on this topic that outline a coherent and principled approach to API design?
Matthias Ettrich's talk at aKedemy 2004 about Qt API was interesting: http://ktown.kde.org/akademy/Matthias_Ettrich_Designing_Qt-style_APIs_audio.... http://ktown.kde.org/akademy/Matthias_Ettrich_Designing_Qt-style_APIs_video.... He emphasis that with a good API, you should not need to lookup the documentation to read and understand what a program does. One of the best bad example is the use of boolean as arguments. For an example taken from Sytem.Directory: createDirectoryIfMissing True "/tmp/foo/bar" What does this True means? Looking up the doc, it says "If the first argument is True the function will also create all parent directories if they are missing." Using specially crafted constructors can often easily improve this. i.e. : createDirectoryIfMissing CreateParent "/tmp/foo/bar" Oleg's keyword arguments [1] also seems a good tool for good APIs in Haskell. Cheers, Jérémy. [1] http://www.haskell.org/pipermail/haskell/2004-August/014416.html