Re: [boost] boost/filesystem/directory.hpp attached for comment

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
 >boost/filesystem/directory.hpp
 >>
 >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 
confusing.

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
 >attributes?

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,

--Beman