On Friday, 18 July 2014 at 18:49:13 UTC, H. S. Teoh via Digitalmars-d wrote:
> [...]
> 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

I think the alternatives you gave show that you are right about this. Everything should be done on a case-by-case basis with the schemes mentioned being just some ideas you could choose from to help find a good name.

On 7/18/2014 12:40 PM, Tourist wrote:
> Are you planning to deprecate the non-lazy functions at some (maybe very
> distant) point?

No. Phobos has already gone through multiple rounds of renaming/deprecation, all at considerable disruption. Each one was supposed to be "worth it" and the "last time". It needs to stop.


> If yes, I agree that it's a good opportunity for a cleanup, and
> there's no point to add prefixes/suffixes.

I object to the characterization that changing the names is a "cleanup", as if the current names are just screwups.


General comment (not particularly directed at Tourist):

There is no such thing as the perfect set of names and the perfect naming convention. These discussions about which of "car", "auto", "vehicle" is more intuitive give the illusion of sage discussions on issues of note, but are really just bikeshedding. There is no correct solution, and no possibility of consensus. Coding styles and best practices also change, making earlier name choices seem quaint, but that still doesn't justify renaming them all to the latest fashion.

I can't understand any user caring if a function is named "setExt" or "setExtension" or "withExtension". It's more like he needs a function that sets a filename extension, he finds it, uses it, and moves on.

What matters is what setExt() actually does, which is provide a lazy algorithm designed to be composable and not make decisions about how needed memory is allocated, thereby providing maximum flexibility and utility to the user.

I find these interminable naming threads to be frustrating and an impediment to progress on issues with Phobos that actually matter, like making Phobos usable for people who don't want to use the GC.

My bias is to give strong preference in names to the choice of the person who actually wrote the code in question. I agree that there are sometimes bad name choices that need some correction. Heck, I agreed to change peek/poke to volatileLoad/volatileStore because sound reasons were presented. I am not absolutely opposed to changing names, but let's keep things in perspective and work on things that matter.

On Friday, 18 July 2014 at 19:00:56 UTC, Walter Bright wrote:
> On 7/18/2014 10:59 AM, Brad Anderson wrote:
>> What do you think?
>
> I'd leaven that proposal with the observation that functions are likely to be lexically sorted by name. Hence, like functions should lexicographically be adjacent to each other.
>
> "setExtension" and "withExtension" will be widely separated, and a user looking for such a function will likely see only one of them and not be aware of the other, which may be a better fit for him.

I really don't see the lexicographic sort order as a big priority here. We have cross referencing to show related functions already and that does a much better job. The only time lexicographic ordering comes into play is with the current naive jump list generation which does a terrible job because it lexicographically sorts everything in the module regardless of scope so things like enum values are scattered throughout the list. ddox does better but still the handwritten category jump lists are much, much better and don't rely automatic sorting.

> Note that Microsoft often adds the suffix "Ex" when creating a new version of an API function. It works well because the new and old will be sorted right next to each other. I'm not suggesting that these ranges add that particular suffix, just pointing out what others do.

The most obvious suffix would be "Lazy" but I think most of us agree we don't want that. When I'm using the Windows API I always have to look up if I should be using the regular or the Ex version and it's not always obvious until you've read a surprising amount on the respective MSDN pages. I seem to recall there are now some "ExEx" functions too. I'm not really a fan but it is an option.

On Friday, 18 July 2014 at 20:35:33 UTC, Walter Bright wrote:
>
> General comment (not particularly directed at Tourist):
>
> There is no such thing as the perfect set of names and the perfect naming convention. These discussions about which of "car", "auto", "vehicle" is more intuitive give the illusion of sage discussions on issues of note, but are really just bikeshedding. There is no correct solution, and no possibility of consensus. Coding styles and best practices also change, making earlier name choices seem quaint, but that still doesn't justify renaming them all to the latest fashion.

There is no renaming being proposed. I don't know why the idea of renaming keeps being brought up. This is not related in any way to the phobos renaming that has traumatized you in the past.

> I can't understand any user caring if a function is named "setExt" or "setExtension" or "withExtension". It's more like he needs a function that sets a filename extension, he finds it, uses it, and moves on.

It's kind of weird that you'd say that because you seem to be pretty strongly opinionated about the naming.

> What matters is what setExt() actually does, which is provide a lazy algorithm designed to be composable and not make decisions about how needed memory is allocated, thereby providing maximum flexibility and utility to the user.

I agree and we kind of discovered elsewhere in this thread that setExtention is actually kind of an odd-man-out. Most functions, especially in std.string, have pretty obvious names to use so this thread as mostly just resulted in some good ideas for how to approach the necessary new names on a case-by-case basis so it's been valuable.

> I find these interminable naming threads to be frustrating and an impediment to progress on issues with Phobos that actually matter, like making Phobos usable for people who don't want to use the GC.

The idea of creating this thread was to address the one remaining problem and get your stalled pull request merged. It seemed appropriate to bring up the issue since your pull request is the prototype for the effort and is something every other lazifying pull request will have to consider. I wanted to make it so we wouldn't have to bicker about naming with every pull request that comes in by trying to head off that problem at the pass.

> My bias is to give strong preference in names to the choice of the person who actually wrote the code in question.

That's really no way to write a standard library. The naming should be just as open to review as the implementation. People care a bit too much about naming but caring too little is also a problem. Intuitive naming is a valuable thing to have. Nobody wants to be constantly looking up function names because it's just a roll of the dice how the name ended up.

> [...]

On Fri, Jul 18, 2014 at 09:14:44PM +0000, Brad Anderson via Digitalmars-d wrote:
> On Friday, 18 July 2014 at 20:35:33 UTC, Walter Bright wrote:
[...]
> >I find these interminable naming threads to be frustrating and an impediment to progress on issues with Phobos that actually matter, like making Phobos usable for people who don't want to use the GC.
> 
> The idea of creating this thread was to address the one remaining problem and get your stalled pull request merged. It seemed appropriate to bring up the issue since your pull request is the prototype for the effort and is something every other lazifying pull request will have to consider. I wanted to make it so we wouldn't have to bicker about naming with every pull request that comes in by trying to head off that problem at the pass.
[...]

On that note, can we please just name the function "withExtension" in that PR, and get it merged? That's the fastest way to terminate these frustrating, interminable threads and start moving somewhere. ;-)


T

-- 
"You are a very disagreeable person." "NO."

On 7/18/2014 2:14 PM, Brad Anderson wrote:
> It's kind of weird that you'd say that because you seem to be pretty strongly
> opinionated about the naming.

It's not just this one, it comes up again and again, always spawning long debates, and accomplishing next to nothing.


>> I find these interminable naming threads to be frustrating and an impediment
>> to progress on issues with Phobos that actually matter, like making Phobos
>> usable for people who don't want to use the GC.
> The idea of creating this thread was to address the one remaining problem

There is no solution, there is just more discussion and more debate, and useful work is not getting done.


> and
> get your stalled pull request merged. It seemed appropriate to bring up the
> issue since your pull request is the prototype for the effort and is something
> every other lazifying pull request will have to consider. I wanted to make it so
> we wouldn't have to bicker about naming with every pull request that comes in by
> trying to head off that problem at the pass.

A naming convention implies a mass renaming of existing lazy algorithms - or it is not a convention at all.

Lazy algorithms are not a new invention in Phobos. They've been there since the beginning of range use. setExt is not a prototype for lazy ranges, we already have them in plenty. It's a prototype for removing storage allocation from Phobos functions, making them more composable, etc.


>> My bias is to give strong preference in names to the choice of the person who
>> actually wrote the code in question.
>
> That's really no way to write a standard library. The naming should be just as
> open to review as the implementation. People care a bit too much about naming
> but caring too little is also a problem. Intuitive naming is a valuable thing to
> have. Nobody wants to be constantly looking up function names because it's just
> a roll of the dice how the name ended up.

Whether "setExtension" or "withExtension" is more intuitive is caring too much. Calling it "sdjfhalkjshdfjh" is caring too little.

On Friday, 18 July 2014 at 22:37:26 UTC, Walter Bright wrote:
> On 7/18/2014 2:14 PM, Brad Anderson wrote:
>> It's kind of weird that you'd say that because you seem to be pretty strongly
>> opinionated about the naming.
>
> It's not just this one, it comes up again and again, always spawning long debates, and accomplishing next to nothing.
>

Oftentimes this is true and I share your dread of long debates (which is why I mentioned bikeshedding in the initial post). This isn't a "let's make better names for the sake of having nicer names" post though. This post was to talk about a real, upcoming problem for which adding a new name for the functions involved is the only option.

> [...]
> There is no solution, there is just more discussion and more debate, and useful work is not getting done.

Yes, there will always be dissenting opinions on naming but I've spent more time arguing with you about whether or not this is a waste of time than it took for us to come up with some great names to use for all the std.string and std.path functions elsewhere in this thread.

> [...]
> A naming convention implies a mass renaming of existing lazy algorithms - or it is not a convention at all.
>
> Lazy algorithms are not a new invention in Phobos. They've been there since the beginning of range use. setExt is not a prototype for lazy ranges, we already have them in plenty. It's a prototype for removing storage allocation from Phobos functions, making them more composable, etc.

It's not a convention for lazy functions. It's just a discussion about how to approach the naming problem you discovered. The fact that the functions are lazy has nothing to do with this. The only thing the functions being discussed have in common is that they need alternative but very similar names because of a technical issue (in an ideal world there would be no need to change the names at all). That the new functions are to solve the allocation decision problem or that they are lazy makes no difference here. It could be any problem in which we can't just use an overload to address.

> Whether "setExtension" or "withExtension" is more intuitive is caring too much. Calling it "sdjfhalkjshdfjh" is caring too little.

Well, it's "setExt" versus "withExtension" but I agree we've wasted too much time on this detail.

To summarize what I think are the best ideas so far:

std.string
----------

  Eager            Lazy
  -----            ----
  capitalize       capitalized
  center           centered
  detab            detabbed
  entab            entabbed
  format           formatted
  leftJustify      leftJustified
  munch            munched
  outdent          outdented
  removechars      charsRemoved
  rightJustify     rightJustified
  splitLines       (none, uses splitter)
  squeeze          squeezed
  strip            stripped
  stripLeft        leftStripped
  stripRight       rightStripped
  succ             successor
  toLower          lowercased
  toStringz        nullTerminated
  toUpper          uppercased
  translate        translated
  wrap             wrapped

std.path
--------

  Eager                Lazy
  -----                ----
  absolutePath         absolutePathOf *
  buildNormalizedPath  asNormalizedPath *
  buildPath            asPath *
  defaultExtension     withDefaultExtension *
  dirName              dirNameOf *
  driveName            driveNameOf *
  expandTilde          tildeExpanded
  relativePath         relativePathOf *
  setExtension         withExtension
  stripDrive           driveStripped
  stripExtension       extensionStripped

* - not terribly happy with these but I'd say it's the best of what's been proposed

Generally it seems like past tense works when the function has a verb, "with" prefix when there is no verb but you are modifying something about the input, and "Of" suffix when you are pulling something out. Also, the verb should come last because it has a better ring to it.

On 07/18/2014 09:23 PM, Meta wrote:
> On Friday, 18 July 2014 at 17:59:05 UTC, Brad Anderson wrote:
>> On Friday, 18 July 2014 at 08:48:08 UTC, Walter Bright wrote:
>>> [...]
>>> Since there are a lot of existing lazy algorithms in Phobos that do
>>> not follow this naming convention, either the convention is pointless
>>> or we go through yet another round of changing Phobos names and
>>> breaking everyone's code.
>>
>> ...
>
> What user is going to think that's intuitive? It's not a bad idea, but
> it's terribly complicated and it doesn't even indicate the critical
> property of the function: that it's lazy. Let's just prepend -Lazy to
> the name and call it a day. Why prepend instead of append? Because the
> names will be sorted in lexical order and we want abbrevLazy to show up
> right below abbrev.
>
> - abbrev         : abbrevLazy
> - capitalize     : capitalizeLazy
> - center         : centerLazy
> - detab          : detabLazy
> - entab          : entabLazy
> - format         : formatLazy
> - leftJustify    : leftJustifyLazy
> - munch          : munchLazy
> - outdent        : outdentLazy
> - removechars    : removedCharsLazy
>
> ...etc.

No please.

- It's too long.

- lazyLazy(lazyLazyLazy,lazyLazy.lazyLazyLazy).

- There are already lazy ranges that do not have the suffix.

On Saturday, 19 July 2014 at 00:05:55 UTC, Brad Anderson wrote:
> To summarize what I think are the best ideas so far:
>
> std.string
> ----------
>
>   Eager            Lazy
>   -----            ----
>   capitalize       capitalized
>   center           centered
>   detab            detabbed
>   entab            entabbed
>   format           formatted
>   leftJustify      leftJustified
>   munch            munched
>   outdent          outdented
>   removechars      charsRemoved
>   rightJustify     rightJustified
>   splitLines       (none, uses splitter)
>   squeeze          squeezed
>   strip            stripped
>   stripLeft        leftStripped
>   stripRight       rightStripped
>   succ             successor
>   toLower          lowercased
>   toStringz        nullTerminated
>   toUpper          uppercased
>   translate        translated
>   wrap             wrapped
>
> std.path
> --------
>
>   Eager                Lazy
>   -----                ----
>   absolutePath         absolutePathOf *
>   buildNormalizedPath  asNormalizedPath *
>   buildPath            asPath *
>   defaultExtension     withDefaultExtension *
>   dirName              dirNameOf *
>   driveName            driveNameOf *
>   expandTilde          tildeExpanded
>   relativePath         relativePathOf *
>   setExtension         withExtension
>   stripDrive           driveStripped
>   stripExtension       extensionStripped
>
> * - not terribly happy with these but I'd say it's the best of what's been proposed
>
> Generally it seems like past tense works when the function has a verb, "with" prefix when there is no verb but you are modifying something about the input, and "Of" suffix when you are pulling something out. Also, the verb should come last because it has a better ring to it.

I think it is worth while having this discussion even though it does seem like we're bike shedding. These names will be set in stone for the foreseeable future so having a quick upfront discussion is worth it IMHO.

As for the above proposed names i really like these names a lot. I think they offer a good convention for lazy versions *and* they sit nearby in the documentation.