On Mon, Aug 24, 2009 at 11:59 PM, Duncan
Coutts
On Mon, 2009-08-24 at 09:59 +0200, Johan Tibell wrote: Yes, I think this is a trap that we often fall into, that we think we make libraries better by providing exactly the one function that people need, in some kind of "high level" "all in one" operation.
As an example, I'm going to pick on Don because I know he can take it ;-).
I think I mentioned this to Don months ago when I decided to against using the library due to all the dependencies. :)
Let the user / caller do the composition. The API is simpler and easier to understand if the user does the composition rather than providing every use case. Also the package dependencies are much simpler.
Sure, point out in the docs that the user could use it that way with other libs but don't provide every composition in the name of convenience.
A Microsoft blogger has a nice short (and rather sarky) article on this topic:
"Programming means that sometimes you have to snap two blocks together" http://blogs.msdn.com/oldnewthing/archive/2009/08/04/9856634.aspx
Another example: At work we have a File class that has a whopping 20 methods for opening a file. Most methods are combinations of different ways to do error handling, locking, setting attributes and options. The whole class has more than 100 methods! I've seen arguments on the form Lots of people write programs that contains the function foo = bar . baz. Therefor we should put foo in library X. on the libraries list lately. I think this argument is bogus most of the time. If you want 'foo', stick it at the top of your module. New functions should add functionality that is difficult to express using the current set of functions in the library. -- Johan