digitalmars.D - Naming of new lazy versions of existing Phobos functions
- Brad Anderson (27/27) Jul 17 2014 Walter's prototype[1] for removing allocations from a phobos
- H. S. Teoh via Digitalmars-d (6/20) Jul 17 2014 I like "with".
- Walter Bright (15/39) Jul 18 2014 Since there are a lot of existing lazy algorithms in Phobos that do not ...
- Brad Anderson (75/85) Jul 18 2014 I'm not suggesting we rename anything. The convention would be
- Brad Anderson (3/4) Jul 18 2014 abbrev actually doesn't belong in this list. I probably included
- =?UTF-8?B?QWxpIMOHZWhyZWxp?= (7/10) Jul 18 2014 Haha! We can't keep it abbreviated anymore though. Wait, what? :p
- H. S. Teoh via Digitalmars-d (63/127) Jul 18 2014 Yeah, "with" doesn't fit everywhere, only in some places. I think
- Brad Anderson (6/21) Jul 18 2014 I think the alternatives you gave show that you are right about
- Brad Anderson (48/48) Jul 18 2014 To summarize what I think are the best ideas so far:
- Gary Willoughby (8/56) Jul 19 2014 I think it is worth while having this discussion even though it
- Dicebot (2/50) Jul 19 2014 I like this list.
- Dmitry Olshansky (4/51) Jul 19 2014 +1
- Jonathan M Davis (8/56) Jul 20 2014 Do we really want to be naming functions which aren't properties
- Dicebot (3/5) Jul 20 2014 Yes. We have parens for denoting functions.
- Tobias Pankrath (4/11) Jul 20 2014 I think it is appropiate to use adjectives for lazy functions.
- Walter Bright (11/12) Jul 18 2014 I'd leaven that proposal with the observation that functions are likely ...
- Brad Anderson (17/31) Jul 18 2014 I really don't see the lexicographic sort order as a big priority
- Meta (18/25) Jul 18 2014 What user is going to think that's intuitive? It's not a bad
- Timon Gehr (5/31) Jul 18 2014 No please.
- Tourist (5/34) Jul 18 2014 Are you planning to deprecate the non-lazy functions at some
- Walter Bright (29/33) Jul 18 2014 No. Phobos has already gone through multiple rounds of renaming/deprecat...
- Brad Anderson (25/49) Jul 18 2014 There is no renaming being proposed. I don't know why the idea of
- H. S. Teoh via Digitalmars-d (9/21) Jul 18 2014 [...]
- Walter Bright (13/32) Jul 18 2014 It's not just this one, it comes up again and again, always spawning lon...
- Brad Anderson (24/44) Jul 18 2014 Oftentimes this is true and I share your dread of long debates
- Yota (2/10) Jul 21 2014 Is an alternate module an option? std.string.lazy, etc.
Walter's prototype[1] for removing allocations from a phobos
function (std.path.setExtension) got hung up on the naming of the
function. It couldn't keep the same name because it differed only
by return type.
Walter doesn't like explicitly naming them as lazy because
existing lazy functions like most of std.algorithm don't have
names that state they are lazy. On the other hand, setExt is
controversial because it's an arbitrary abbreviation done just to
avoid the naming conflict. Not every function we'd like to see
adopt the same approach would be amenable to a simple
abbreviation to dodge the naming issue.
I think it's probably a good time to come up with a naming scheme
for these lazy versions of existing functions so things are
consistent throughout Phobos.
David Nadlinger offered a few ideas in the thread:
setExtensionLazy, extensionSetter, or withExtension.
I find the "with" prefix particularly attractive. It implies the
lazy behavior, is short, and reads well when chained with other
calls. Hypothetical example I gave in the Pull Request comments:
auto contents =
" FILE".withStrip()
.withLowercase()
.withExtension(".txt")
.readText();
At the risk of bikeshedding, I thought it would be useful to
solicit the wider forum audience for ideas and opinions. Thoughts?
1. https://github.com/D-Programming-Language/phobos/pull/2149
Jul 17 2014
"H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com>
On Thu, Jul 17, 2014 at 10:59:26PM +0000, Brad Anderson via Digitalmars-d wrote:
[...]
I find the "with" prefix particularly attractive. It implies the lazy
behavior, is short, and reads well when chained with other calls.
Hypothetical example I gave in the Pull Request comments:
auto contents =
" FILE".withStrip()
.withLowercase()
.withExtension(".txt")
.readText();
At the risk of bikeshedding, I thought it would be useful to solicit
the wider forum audience for ideas and opinions. Thoughts?
1. https://github.com/D-Programming-Language/phobos/pull/2149
I like "with".
T
--
Once the bikeshed is up for painting, the rainbow won't suffice. -- Andrei
Alexandrescu
Jul 17 2014
On 7/17/2014 3:59 PM, Brad Anderson wrote:Walter's prototype[1] for removing allocations from a phobos function (std.path.setExtension) got hung up on the naming of the function. It couldn't keep the same name because it differed only by return type. Walter doesn't like explicitly naming them as lazy because existing lazy functions like most of std.algorithm don't have names that state they are lazy. On the other hand, setExt is controversial because it's an arbitrary abbreviation done just to avoid the naming conflict. Not every function we'd like to see adopt the same approach would be amenable to a simple abbreviation to dodge the naming issue.A good summary.I think it's probably a good time to come up with a naming scheme for these lazy versions of existing functions so things are consistent throughout Phobos. David Nadlinger offered a few ideas in the thread: setExtensionLazy, extensionSetter, or withExtension. I find the "with" prefix particularly attractive. It implies the lazy behavior, is short, and reads well when chained with other calls. Hypothetical example I gave in the Pull Request comments: auto contents = " FILE".withStrip() .withLowercase() .withExtension(".txt") .readText(); At the risk of bikeshedding, I thought it would be useful to solicit the wider forum audience for ideas and opinions. Thoughts? 1. https://github.com/D-Programming-Language/phobos/pull/2149Since 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. I haven't completely sold Andrei on the idea, but I feel that all algorithms should be lazy unless they have a very strong reason not to be. Being the default suggests a naming convention for them would be unnecessary even if it were practical. I also suggest that ext is not an arbitrary abbreviation for extension, it is commonplace. In a module named std.path, there's little doubt about what it means. And besides, "extension" itself is an abbreviation for "file name extension". I don't really want to go the Java approach of reallyLongSentencesAsIdentifierNames either, as those are not very practical unless one has an autocompleting IDE.
Jul 18 2014
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.I'm not suggesting we rename anything. The convention would be just for when there is an existing eager function we'd like to add a lazy version of but which we can't use the original name because an overload isn't possible. It's out of necessity, not desire. I wish we didn't need new names.I haven't completely sold Andrei on the idea, but I feel that all algorithms should be lazy unless they have a very strong reason not to be. Being the default suggests a naming convention for them would be unnecessary even if it were practical.Yeah, I agree. I'd hate having a "with" prefix on everything. 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. So here are both options side by side for comparison: - abbrev : abbreviated : withAbbrev - capitalize : capitalized : withCapitalize - center : centered : withCenter - detab : detabbed : withDetab - entab : entabbed : withEntab - format : formatted : withFormat - leftJustify : leftJustified : withLeftJustify - munch : munched : withMunch - outdent : outdented : withOutdent - removechars : removedChars : withRemoveChars - rightJustify : rightJustified : withRightJustify - splitLines : splittedLines : withSplitLines - squeeze : squeezed* : withSqueeze - strip : stripped : withStrip - stripLeft : strippedLeft : withStripLeft - stripRight : strippedRight : withStripRight - succ : ? : withSucc - toLower : lowered : withLower - toStringz : ? : withStringz - toUpper : uppered : withUpper - tr : ? : withTr - 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. Not sure what to do about tr and toStringz. 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). 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). 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. 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. Let's try using this rule with std.path: - absolutePath : withAbsolutePath - buildNormalizedPath : builtNormalizedPath (maybe normalizedPath) - buildPath : builtPath (maybe path) - defaultExtension : defaultedExtension (maybe ensureExtension) - dirName : withDirName (maybe dirNameOnly) - driveName : withDriveName (maybe driveNameOnly) - expandTilde : expandedTilde - relativePath : withRelativePath - setExtension : withExtension - stripDrive : strippedDrive - stripExtension : strippedExtension 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. The rule seems to work ok. Not nearly as clean and nice as it applies to std.string though. What do you think?
Jul 18 2014
On Friday, 18 July 2014 at 17:59:05 UTC, Brad Anderson wrote:- abbrev : abbreviated : withAbbrevabbrev actually doesn't belong in this list. I probably included a few others mistakenly too.
Jul 18 2014
On 07/18/2014 10:59 AM, Brad Anderson wrote:maybe use the past participle on the ones with verbs.I vote 100% for past participle, 20% for "with".- abbrev : abbreviated : withAbbrevHaha! We can't keep it abbreviated anymore though. Wait, what? :p- removechars : removedChars : withRemoveCharsIt is better when the verb is at the end: charsRemoved, leftStripped (of course not to mean "has been left in a stripped state" :p), rightStripped, etc. Ali
Jul 18 2014
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 : withCenterI 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 : withFormatditto [...]- succ : ? : withSuccUgh. "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 : withLowerUgh. What about "lowercased"?- toStringz : ? : withStringz"nullTerminated"?- toUpper : uppered : withUpperPlease, "uppercased". "uppered" is just horrible in so many ways.- tr : ? : withTrIs 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 -> nullTerminatedI 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. :-PsetExtension 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 : withAbsolutePathI 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 : expandedTildetildeExpanded.- relativePath : withRelativePathNo, that sounds backwards. I propose "relativePathOf".- setExtension : withExtensionOK.- stripDrive : strippedDrive - stripExtension : strippedExtensionSounds 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
Jul 18 2014
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.
Jul 18 2014
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.
Jul 18 2014
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.
Jul 19 2014
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 like this list.
Jul 19 2014
19-Jul-2014 04:05, Brad Anderson пишет:
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.
+1
--
Dmitry Olshansky
Jul 19 2014
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.Do we really want to be naming functions which aren't properties with adjectives instead of verbs? That seems very wrong to me. I'd much rather see stuff like setExt or setExtLazy than withExtension or extensionSet. Function names are supposed to be verbs unless they're emulating variables. They _do_ something, even if it's lazy. - Jonathan M Davis
Jul 20 2014
On Sunday, 20 July 2014 at 10:19:10 UTC, Jonathan M Davis wrote:Do we really want to be naming functions which aren't properties with adjectives instead of verbs?Yes. We have parens for denoting functions. Oh wait.
Jul 20 2014
Do we really want to be naming functions which aren't properties with adjectives instead of verbs? That seems very wrong to me. I'd much rather see stuff like setExt or setExtLazy than withExtension or extensionSet. Function names are supposed to be verbs unless they're emulating variables. They _do_ something, even if it's lazy. - Jonathan M DavisI think it is appropiate to use adjectives for lazy functions. The "Use verbs for functions"-rule holds no ground in lazy evaluation, except you want to call them "wrapInExtensionSetter" or something like that.
Jul 20 2014
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. 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.
Jul 18 2014
On Friday, 18 July 2014 at 19:00:56 UTC, Walter Bright wrote:On 7/18/2014 10:59 AM, Brad Anderson wrote: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.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.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.
Jul 18 2014
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: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.[...] 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....
Jul 18 2014
On 07/18/2014 09:23 PM, Meta wrote:On Friday, 18 July 2014 at 17:59:05 UTC, Brad Anderson wrote:No please. - It's too long. - lazyLazy(lazyLazyLazy,lazyLazy.lazyLazyLazy). - There are already lazy ranges that do not have the suffix.On Friday, 18 July 2014 at 08:48:08 UTC, Walter Bright wrote: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.[...] 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....
Jul 18 2014
On Thursday, 17 July 2014 at 22:59:27 UTC, Brad Anderson wrote:
Walter's prototype[1] for removing allocations from a phobos
function (std.path.setExtension) got hung up on the naming of
the function. It couldn't keep the same name because it
differed only by return type.
Walter doesn't like explicitly naming them as lazy because
existing lazy functions like most of std.algorithm don't have
names that state they are lazy. On the other hand, setExt is
controversial because it's an arbitrary abbreviation done just
to avoid the naming conflict. Not every function we'd like to
see adopt the same approach would be amenable to a simple
abbreviation to dodge the naming issue.
I think it's probably a good time to come up with a naming
scheme for these lazy versions of existing functions so things
are consistent throughout Phobos.
David Nadlinger offered a few ideas in the thread:
setExtensionLazy, extensionSetter, or withExtension.
I find the "with" prefix particularly attractive. It implies
the lazy behavior, is short, and reads well when chained with
other calls. Hypothetical example I gave in the Pull Request
comments:
auto contents =
" FILE".withStrip()
.withLowercase()
.withExtension(".txt")
.readText();
At the risk of bikeshedding, I thought it would be useful to
solicit the wider forum audience for ideas and opinions.
Thoughts?
1. https://github.com/D-Programming-Language/phobos/pull/2149
Are you planning to deprecate the non-lazy functions at some
(maybe very distant) point? If yes, I agree that it's a good
opportunity for a cleanup, and there's no point to add
prefixes/suffixes.
Jul 18 2014
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.
Jul 18 2014
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.[...]
Jul 18 2014
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:[...][...] 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."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.
Jul 18 2014
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.There is no solution, there is just more discussion and more debate, and useful work is not getting done.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 problemand 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.Whether "setExtension" or "withExtension" is more intuitive is caring too much. Calling it "sdjfhalkjshdfjh" is caring too little.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.
Jul 18 2014
On Friday, 18 July 2014 at 22:37:26 UTC, Walter Bright wrote:On 7/18/2014 2:14 PM, Brad Anderson wrote: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.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.[...] 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.
Jul 18 2014
On Friday, 18 July 2014 at 20:35:33 UTC, Walter Bright wrote:On 7/18/2014 12:40 PM, Tourist wrote:Is an alternate module an option? std.string.lazy, etc.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.
Jul 21 2014