[Haskell-cafe] APIs (was: Unexported functions are evil)

[Jérémy Bobbio]

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.ogg
http://ktown.kde.org/akademy/Matthias_Ettrich_Designing_Qt-style_APIs_video.ogg

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://www.haskell.org//pipermail/haskell-cafe/attachments/20050519/fdab914e/attachment.bin