Naming of new lazy versions of existing Phobos functions

[H. S. Teoh via Digitalmars-d]

On Fri, Jul 18, 2014 at 05:59:03PM +0000, Brad Anderson via Digitalmars-d wrote:
[...]
> Yeah, I agree. I'd hate having a "with" prefix on everything.

Yeah, "with" doesn't fit everywhere, only in some places. I think
"withExtension" (or "withExt") is a very good choice of name. It may
apply to a few other noun-based names, but with verb-based names it's
really ugly ("withCapitalize"? Please, no!).


> I'm just trying to think of a consistent way to approach this issue
> since all of these new lazy functions in Phobos will need new names in
> order for us to move forward with Operation Couchpotato.
> 
> Looking over std.string at all the functions we should probably add
> lazy versions of the only option I can think of apart from "with" is
> maybe use the past participle on the ones with verbs.

I think this is actually a good idea. It did occur to me too.


> So here are both options side by side for comparison:
> 
> - abbrev         : abbreviated    : withAbbrev
> - capitalize     : capitalized    : withCapitalize
> - center         : centered       : withCenter

I think this shows clearly that the past participle form is much better
when a verb is involved in the original name.


> - detab          : detabbed       : withDetab
> - entab          : entabbed       : withEntab

"withDetab"? Ugh! Clearly, "detabbed" is far better!


> - format         : formatted      : withFormat

ditto


[...]
> - succ           : ?              : withSucc

Ugh. "succ" is a bad name to begin with, but "withSucc"?! Wow. I don't
know if we could live with the shame! :-P Maybe the lazy version should
be "successor" -- since after all this *is* our chance to replace bad
names. :-)


> - toLower        : lowered        : withLower

Ugh. What about "lowercased"?


> - toStringz      : ?              : withStringz

"nullTerminated"?


> - toUpper        : uppered        : withUpper

Please, "uppercased". "uppered" is just horrible in so many ways.


> - tr             : ?              : withTr

Is there any reason at all to introduce a lazy version of this, rather
than merging it with "translate"? In fact, if it weren't for the danger
of breaking existing code, I'd say get rid of this altogether.


> - translate      : translated     : withTranslate
> - wrap           : wrapped        : withWrap
> 
> * or squoze, heh
> 
> That actually works surprisingly well for the most part. succ() has a
> bad name anyway so I'd think we'd take the opportunity to just come up
> with a better one for the lazy version.

I'd say take over the original good name: successor. :-)


> Not sure what to do about tr and toStringz.

I vote to *not* do a lazy version of tr, since translate subsumes its
functionality in a much better interface.

toStringz -> nullTerminated


> I left out soundex() and maketrans() because they are kind of
> different beasts (and technically return fixed sizes so a static array
> is probably a better option for these two anyway).

Agreed.


> I also am leaving out to[Lower,Upper]InPlace() because they should
> probably just take an allocator or something (maybe rename them
> finally while we are at it;
> toLowerOftenInPlaceButNotAlwaysBecauseOfVariableWidthEncoding()
> perhaps).

And while we're at it, replace the logo on dlang.org with a coffee cup
and rename the domain to java.org. :-P


> setExtension doesn't work with this approach though. I'd argue using
> "set" in the name was bad in the first place because it's not setting
> anything, it's making something new.

Yeah perhaps it should've been named "replaceExt" or something along
those lines. But anyway, "withExt" sounds like the best lazy name in
this case.


> Maybe "with" could be for functions with no verb or a verb with an
> identical past and present participle, otherwise just use the paste
> tense of the verb.

Yes.


> Let's try using this rule with std.path:
> 
> - absolutePath        : withAbsolutePath

I don't like "with" in this case. How about "absolutePathOf"? Not ideal,
but a notch better than "withAbsolutePath" IMO.


> - buildNormalizedPath : builtNormalizedPath (maybe normalizedPath)

I vote for "normalizedPath".


> - buildPath           : builtPath           (maybe path)

I don't like "path" 'cos it doesn't really describe what it's doing very
well:

	auto components = ["path", "to", "filename"];
	auto pathname = components.path; // huh?

Makes it sound like you're finding the path to the components, rather
than putting them together to make a path. What about "assemblePath"?
(Not that good either, makes it confusing with "buildPath". :-/)

Or maybe "asPath"?


> - defaultExtension    : defaultedExtension  (maybe ensureExtension)

"withDefaultExtension" is better IMO.


> - dirName             : withDirName         (maybe dirNameOnly)

Eeek, no. What about "dirNameOf"?


> - driveName           : withDriveName       (maybe driveNameOnly)

"driveNameOf".


> - expandTilde         : expandedTilde

tildeExpanded.


> - relativePath        : withRelativePath

No, that sounds backwards. I propose "relativePathOf".


> - setExtension        : withExtension

OK.


> - stripDrive          : strippedDrive
> - stripExtension      : strippedExtension

Sounds OK.


> baseName() and extension() just slice (or should just slice, didn't
> look at the implementations) so they were left out. dirName could
> probably be made to not allocate.

If we ever need to, "baseNameOf" and "extensionOf" would work, I think.
"dirName" could be "directoryOf" or "dirOf", perhaps.


> The rule seems to work ok. Not nearly as clean and nice as it applies
> to std.string though.
> 
> What do you think?

I think it's a fool's errand to try to invent a single system of naming
that's blindly applied across the board. We should have some guiding
principles for common cases (like "withXxx", "xxxOf", "verbed", etc.)
for the sake of overall consistency, but we should consider each name on
a case-to-case basis and make appropriate exceptions where it makes more
sense ("tildeExpanded" sounds much better than "withExpandTilde" or
"expandTildeOf" or "expandedTilde", for example).


T

-- 
"The whole problem with the world is that fools and fanatics are always so certain of themselves, but wiser people so full of doubts." -- Bertrand Russell. "How come he didn't put 'I think' at the end of it?" -- Anonymous