From: Beman Dawes (bdawes_at_[hidden])
Date: 2002-03-20 20:03:50
At 05:59 PM 3/20/2002, Dylan Nicholson wrote:
> --- Beman Dawes <bdawes_at_[hidden]> wrote: > Attached (hopefully) is
>Just one comment - stylistically, although having lots of different
>functions with long descriptive names probably makes code a little
>easier to read, it somehow looks inelegant and atypical. Also it
>makes it harder to find documentation for specific function.
>I would tend to coalesce functions with similar functionalities into
>the same function name and add flags for specialised behavior.
>create_missing_directories() stands out in particular - I would expect
>create_directory to simply take a flag (defaulting to false) specifying
>whether it should recursively create the necessary parent directories
>first (like the Unix mkdir utility). Similarly with remove and the
>various forms you have.
I understand each of your points above; indeed my first cut looked a lot
like what you are describing. Here is why the header evolved:
If you look at older libraries, including many I've designed, they had a
relatively small number of functions, with lots of options to tailor for
specific needs. But more modern libraries try to make functions and their
names more specific. Makes efficient implementation possible (dispatch to
particular flavor is done by the compiler rather than at runtime). Aids
understanding (if not carried too far.) For example, the STL has sort,
stable_sort, etc, rather than a single sort with an option argument.
Because these functions (and we are talking perhaps 8 versus 16 free
functions, at the first cut, not 8 versus 50) are in a uncluttered
namespace (boost::filesystem) the documentation isn't likely to be a
problem. This isn't one of those silly API docs where the vendor lists
several thousand functions in alphabetic order. For writing programs, I've
been namespace aliasing boost::filesystem to fs, and the code looks quite
nice to my eye.
If a library has simple, specific, single purpose functions like
remove_directory() and remove_file(), it is possible to build composite
functions, as the proposal does, like remove(). The user has a choice, yet
the number of functions is small enough that the choice isn't seriously
The idea is that for a casual, non-critical script-like program,
programmers will probably just say remove() or even remove_if_exists(), and
not worry about the consequences. But for those mission critical jobs that
take hours or days to complete, careful programmers will use the more
specific functions, and rest assured that an exception will be thrown at
the first hint of trouble. Of course, you could do that with options, but
I prefer the more precisely named function approach.
These are serious points you have brought up, and I've spent days thinking
about them in the past couple of weeks. Of course, the overall issues are
part of the ongoing long-term discussions of how to do the best libraries
for widespread, standard use.
>What's the point of is_read_only? Surely this would be detected through
Yes, it certainly can. My rationale for exists(), is_directory(), and
is_read_only() is that these attributes are so commonly used, and so
universal, that they should always be present, and in the familiar form of
a specifically named function. The same cannot, I think, be said for the
other attributes. Perhaps not the strongest rationale in the world, but
there it is:-)
Thanks for the comments,
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk