Proposal for std.path replacement

[Jonathan M Davis]

On Sunday 06 March 2011 04:31:20 Lars T. Kyllingstad wrote:
> On Sat, 05 Mar 2011 16:32:55 +0000, Lars T. Kyllingstad wrote:
> > On Fri, 04 Mar 2011 08:14:44 -0500, Nick Sabalausky wrote:
> >> "Lars T. Kyllingstad" <public at kyllingen.NOSPAMnet> wrote in message
> >> news:ikofkc$322$1 at digitalmars.com...
> >> 
> >>> As mentioned in the "std.path.getName(): Screwy by design?" thread, I
> >>> started working on a rewrite of std.path a long time ago, but I got
> >>> sidetracked by other things.  The recent discussion got me working on
> >>> it again, and it turned out there wasn't that much left to be done.
> >>> 
> >>> So here it is, please comment:
> >>>    http://kyllingen.net/code/ltk/doc/path.html
> >>>    https://github.com/kyllingstad/ltk/blob/master/ltk/path.d
> >> 
> >> I don't want to jinx it, but there seems to be a lot of agreement in
> >> this thread. Seriously, how often does that happen around here? :)
> > 
> > Not too often, so I take it as a good sign that I'm onto something. ;)
> > 
> > The only disagreement seems to be about the naming, so let's have a
> > round of voting.  Here are a few alternatives for each function.  Please
> > say which ones you prefer.
> > 
> >  * dirSeparator, dirSep, sep
> >  * currentDirSymbol, currentDirSym, curDirSymbol * basename, baseName,
> >  filename, fileName * dirname, dirName, directory, getDir, getDirName *
> >  drivename, driveName, drive, getDrive, getDriveName * extension, ext,
> >  getExt, getExtension * stripExtension, stripExt
> > 
> > (The same convention will be used for stripExtension, replaceExtension
> > and defaultExtension.)
> 
> In summary, it seems currentDirSymbol, baseName, dirName and driveName
> are clear winners.  Less clear, but still voted for by the majority, are
> extension and stripExtension.  It is a tie between dirSep and
> dirSeparator.
> 
> Below are the votes I counted.  And before you say "hey, I didn't know we
> could make suggestions of our own", or "why did that guy get several
> votes?", this was by no means a formal vote.  It was just trying to get a
> feel for people's preferences.  Before the module gets accepted into
> Phobos there will have to be a formal review process, so there is still a
> lot of opportunity to fight over naming. :)
> 
> dirSep: 3 (Nick Sabalausky, spir, Jonathan M. Davis)
> dirSeparator: 3 (Bekenn, Jim, J Chapman)
> 
> currDirSym: 1 (Jonathan M. Davis)
> currDirSymbol: 2 (Nick Sabalausky, Jonathan M. Davis)
> path.current: 1 (Andrej Mitrovic)
> currentDirSymbol: 4 (Bekenn, Jim, J Chapman, spir)
> 
> baseName: 6 (Nick Sabalausky, Bekenn, Jim, J Chapman, spir, Jonathan M.
> Davis)
> baseFileName: 1 (Nick Sabalausky)
> fileName: 1 (spir)
> basename: 1 (Andrei Alexandrescu)
> 
> dirName: 6 (Nick Sabalausky, Bekenn, Jim, spir, Jonathan M. Davis, David
> Nadlinger)
> directory: 1 (Nick Sabalausky)
> getDirName: 2 (J Chapman, spir)
> dirname: 1 (Andrei Alexandrescu)
> 
> driveName: 4 (Nick Sabalausky, Bekenn, Jim, spir)
> drive: 2 (Nick Sabalausky, Jonathan M. Davis)
> getDriveName: 2 (J Chapman, spir)
> driveLetter: 1 (Jonathan M. Davis)
> 
> ext: 1 (Nick Sabalausky)
> extension: 2 (Bekenn, Jim)
> getExtension: 1 (J Chapman)
> 
> stripExt: 2 (Nick Sabalausky, Jonathan M. Davis)
> stripExtension: 3 (Bekenn, Jim, J Chapman)

This is a very small sampling of even the folks here on the newsgroup, let alone 
the D community at large, so I don't think that you can really base all _that_ 
much off of the votes. Rather, I think that you should pretty much do what Andrei 
said and pick what you think is best, but now you have some opinions and 
arguments from other people that you can take into consideration when naming the 
functions. As Andrei said, you're never going to get everyone to agree anyway.

I think that the general guidelines here should be that the names be descriptive 
but as short as they can reasonably be and still be appropriately descriptive. 
Names which are not descriptive enough are likely to not be clear enough, but 
names that are very descriptive but as very long are likely to get very annoying 
- especially if you have to use them often and/or have to deal with a character 
limit per line.

So, take what has been said into consideration and adjust the names as you think 
is appropriate. I'm sure that they'll get debated further when you actually put 
it up for a full review. But naming is arguably _the_ classic bike shedding 
issue. It matters but not in proportion with the amount of discussion and 
arguing that it gets, and you'll _never_ get everyone to agree over it.

On a side note, any functions that have changed behavior should probably have 
names which are different from what's currently in std.path. So, for instance, if 
your basename function has different behavior from the current std.path's 
basename, you should probably give it a different name (in this case, the obvious 
solution is baseName - it actually follows Phobos' naming conventions and was 
the pretty clear favorite in this discussion). Otherwise, you're going to break 
code when your code gets merged into Phobos. If the behavioral change is small, 
the perhaps a new name is not necessary, but I know that Walter is _very_ much 
against breaking code with changes to Phobos, and silently changing behavior on 
someone is one of the worst ways to do that. Fortunately, I believe that pretty 
much all of your functions have new names, but that _is_ something to consider 
when naming stuff.

- Jonathan M Davis