The following symbols in std.string don't satisfy the Phobos naming conventions and need to be renamed:

LS PS capwords countchars entab expandtabs hexdigits icmp iswhite ljustify lowercase maketrans newline octdigits removechars rjustify sformat splitlines stripl stripr tolower tolowerInPlace toupper toupperInPlace tr whitespace zfill

Opinions on what to rename?


Thanks,

Andrei

Andrei Alexandrescu wrote:

> The following symbols in std.string don't satisfy the Phobos naming conventions and need to be renamed:
> 
> LS PS capwords countchars entab expandtabs hexdigits icmp iswhite ljustify lowercase maketrans newline octdigits removechars rjustify sformat splitlines stripl stripr tolower tolowerInPlace toupper toupperInPlace tr whitespace zfill
> 
> Opinions on what to rename?
> 
> 
> Thanks,
> 
> Andrei

Are there any conventions beyond what case to use?

I see this common pattern: verb-noun (expand-tabs) but for what I think is called adverbs in English it is a bit mixed (ljustify vs stripl).


These ones should be simply lower camel case:

capwords countchars entab expandtabs hexdigits octdigits removechars tolower tolowerInPlace toupper toupperInPlace lowercase maketrans splitlines


newline and whitespace: not sure how it is called in English, but these look like they have become single words and are fine.

LS and PS: since these are constants, upper case is ok, although LS is inconsistent with std.path.linesep.

iswhite -> isWhitespace

tr: would say translate, but it's already there. Doesn't it overlap too much?

Then these remain, I'm less sure about them:

icmp ljustify rjustify sformat stripl stripr zfill

Possibly:

icmp: ok, it's a single abbreviation and insensitiveCompare is too much
ljustify -> leftJustify
rjustify -> rightJustify
sformat -> stringFormat (?)
stripl -> leftStrip
stripr -> rightStrip
zfill -> zeroFill (or better, ditch it and overload justify to take the
filling char)

On Thursday 20 January 2011 23:57:39 Andrei Alexandrescu wrote:
> The following symbols in std.string don't satisfy the Phobos naming conventions and need to be renamed:
> 
> LS PS capwords countchars entab expandtabs hexdigits icmp iswhite ljustify lowercase maketrans newline octdigits removechars rjustify sformat splitlines stripl stripr tolower tolowerInPlace toupper toupperInPlace tr whitespace zfill
> 
> Opinions on what to rename?

LS = lineSep
PS = paragraphSep
capwords = capitalizeWords? capWords?
countchars = countChars

Well, entab, I'd argue _does_ follow the naming convention, because entab would be a verb, albeit a made up one. Certainly, en is a prefix, not another word, so I think that entab is fine. If that doesn't fly, then go with enTab, I guess, but I'd argue that entab is a single word and fine as it is.

expandtabs = expandTabs
hexdigits = hexDigits

icmp, I'd actually be tempted to just leave as-is, since it's simple and clear and goes well with cmp. But if that's not acceptable, I guess that I'd suggest cmpIgnoreCase. It is a tad verbose though. Or I suppose that you could just do iCmp.

iswhite = isWS, isWhitespace, or isWhite (I'd probably pick isWS)
ljustify = leftJustify
lowercase = lettersLC
maketrans = makeTransTable

I'd leave newline as is. newline is pretty much used as a single word like that in programming when talking about \n, so I'd consider it one word, and so it's fine as-is.

octdigits = octDigits
removechars = removeChars
rjustify = rightJustify

sformat = formatInPlace? I'm not sure that I quite get what this function does though.

splitlines = splitLines

stripl = stripLeft (though honestly, I kind of like stripl and stripr, and it's
just dumb to capitalize the last letter)
stripr = stripRight

tolower = toLower
tolowerInPlace = toLowerInPlace
toupper = toUpper
toupperInPlace = toUpperInPlace

tr? The name means nothing to me. I haven't a clue where the name comes from, so I can't really give a better version of the same name. As it is, tr seems fine to me, particularly since tR just seems stupid. It should probably get a more descriptive name though. replaceChars?

Similar to newline, I'd consider whitespace to be one word and just fine as is. After all, you don't type new line or white space when talking about newlines or whitespace.  newline and whitespace are both whole words with special meaning in the world of programming.

zfill is just a weird name. It's slighty better than tr in that it does "fill" in the string, but truth be told, without reading the source code, I don't know what it really does. I would _expect_ that the justify functions would move whatever space was around the string to the left, right, or both depending on which justify function you use, but I don't know. And how would that relate to filling in the string with 0's? Does it use 0 instead of spaces? The simplest would be to just rename it zFill, but unless zfill is a semi-standard/common name from other languages or libraries, a more descriptive name might be preferable. I have no idea what that would be though.

- Jonathan M Davis

On Friday 21 January 2011 00:44:26 Jonathan M Davis wrote:
> On Thursday 20 January 2011 23:57:39 Andrei Alexandrescu wrote:
> > The following symbols in std.string don't satisfy the Phobos naming conventions and need to be renamed:
> > 
> > LS PS capwords countchars entab expandtabs hexdigits icmp iswhite ljustify lowercase maketrans newline octdigits removechars rjustify sformat splitlines stripl stripr tolower tolowerInPlace toupper toupperInPlace tr whitespace zfill
> > 
> > Opinions on what to rename?
> 
> LS = lineSep
> PS = paragraphSep
> capwords = capitalizeWords? capWords?
> countchars = countChars
> 
> Well, entab, I'd argue _does_ follow the naming convention, because entab would be a verb, albeit a made up one. Certainly, en is a prefix, not another word, so I think that entab is fine. If that doesn't fly, then go with enTab, I guess, but I'd argue that entab is a single word and fine as it is.
> 
> expandtabs = expandTabs
> hexdigits = hexDigits
> 
> icmp, I'd actually be tempted to just leave as-is, since it's simple and clear and goes well with cmp. But if that's not acceptable, I guess that I'd suggest cmpIgnoreCase. It is a tad verbose though. Or I suppose that you could just do iCmp.
> 
> iswhite = isWS, isWhitespace, or isWhite (I'd probably pick isWS)
> ljustify = leftJustify
> lowercase = lettersLC
> maketrans = makeTransTable
> 
> I'd leave newline as is. newline is pretty much used as a single word like that in programming when talking about \n, so I'd consider it one word, and so it's fine as-is.
> 
> octdigits = octDigits
> removechars = removeChars
> rjustify = rightJustify
> 
> sformat = formatInPlace? I'm not sure that I quite get what this function does though.
> 
> splitlines = splitLines
> 
> stripl = stripLeft (though honestly, I kind of like stripl and stripr, and
> it's just dumb to capitalize the last letter)
> stripr = stripRight
> 
> tolower = toLower
> tolowerInPlace = toLowerInPlace
> toupper = toUpper
> toupperInPlace = toUpperInPlace
> 
> tr? The name means nothing to me. I haven't a clue where the name comes from, so I can't really give a better version of the same name. As it is, tr seems fine to me, particularly since tR just seems stupid. It should probably get a more descriptive name though. replaceChars?
> 
> Similar to newline, I'd consider whitespace to be one word and just fine as is. After all, you don't type new line or white space when talking about newlines or whitespace.  newline and whitespace are both whole words with special meaning in the world of programming.
> 
> zfill is just a weird name. It's slighty better than tr in that it does "fill" in the string, but truth be told, without reading the source code, I don't know what it really does. I would _expect_ that the justify functions would move whatever space was around the string to the left, right, or both depending on which justify function you use, but I don't know. And how would that relate to filling in the string with 0's? Does it use 0 instead of spaces? The simplest would be to just rename it zFill, but unless zfill is a semi-standard/common name from other languages or libraries, a more descriptive name might be preferable. I have no idea what that would be though.
> 
> - Jonathan M Davis

Also, I'd suggest that we not be OCD about our naming conventions. We should strive to stick to camel-casing function names with the first letter being lowercase, but if there's a function that just looks better not quite following the conventions, then we should go with that - particularly if camel-casing everything leads to really long names everywhere.

For instance, I have no problem with stripl. I think that it would be stupid to just make the last letter uppercase, and stripLeft is more verbose. The same goes for icmp. icmp fits really well with cmp, and pretty much anything which tries to camel-case it becomes excessively verbose.

So, I think that we should generally follow our naming conventions, but I don't think that we should absolutely require that they be followed _exactly_ all the time - just like sometimes it's better to format code somewhat differently from what a coding standard requires, because in a particular case, the result of following the standard would be much harder to read, even if following the standard _normally_ leads to more readable code.

- Jonathan M Davis

On Fri, 21 Jan 2011 01:57:39 -0600, Andrei Alexandrescu wrote:

> The following symbols in std.string don't satisfy the Phobos naming conventions and need to be renamed:
> 
> LS PS capwords countchars entab expandtabs hexdigits icmp iswhite ljustify lowercase maketrans newline octdigits removechars rjustify sformat splitlines stripl stripr tolower tolowerInPlace toupper toupperInPlace tr whitespace zfill
> 
> Opinions on what to rename?


I think the following are fine, because you would most likely write them as single words in ordinary text:

  entab, lowercase, newline, whitespace

These should simply be camelCased:

  countChars, expandTabs, hexDigits, removeChars, splitLines,
  toLower, toLowerInPlace, toUpper, toUpperInPlace

These should be expanded a bit and camelCased:

  LS:        lineSep, lineSeparator
  PS:        paragraphSep, paragraphSeparator
  capwords:  capitalizeWords
  iswhite:   isWhitespace
  ljustify:  leftJustify
  maketrans: makeTranslation
  octdigits: octalDigits
  rjustify:  rightJustify
  sformat:   formatString
  stripl:    stripLeft
  stripr:    stripRight
  zfill:     zeroFill

I don't know about icmp.  I guess I would prefer both cmp and icmp to be renamed to compare and compareCaseInsensitive.

I really have no idea what to call tr.

-Lars

On Fri, 21 Jan 2011 09:05:24 +0000, Lars T. Kyllingstad wrote:

>   sformat:   formatString

Forget that; I confused sformat() and format().  But maybe sformat should be renamed formatInPlace?  I dunno.

-Lars

On 2011-01-21 08:57, Andrei Alexandrescu wrote:
> The following symbols in std.string don't satisfy the Phobos naming
> conventions and need to be renamed:
>
> LS PS capwords countchars entab expandtabs hexdigits icmp iswhite
> ljustify lowercase maketrans newline octdigits removechars rjustify
> sformat splitlines stripl stripr tolower tolowerInPlace toupper
> toupperInPlace tr whitespace zfill
>
> Opinions on what to rename?
>
>
> Thanks,
>
> Andrei

LS -> lineSeparator/LineSeparator
PS -> paragraphSeparator/ParagraphSeparator
capwords -> capitalizeWords/capitalizeAll // should this function really mess with whitespaces ?

countchars -> countChars/count
entab -> entab/spacesToTabs
expandtabs -> expandTabs/tabsToSpaces
hexdigits -> hexDigits
icmp -> insensitiveCompare
iswhite -> isWhitespace
ljustify -> leftJustify /justifyLeft
lowercase -> lowercaseChars
maketrans -> makeTranslationTable // is this really needed, can't translate to this

newline -> newline
octdigits -> octalDigits
removechars -> removeChars/remove
rjustify -> rightJustify/justifyRight
sformat -> formatInPlace
splitlines -> splitLines
stripl -> stripLeft
stripr -> striptRight
tolower -> toLower/toLowercase/toLowerCase
tolowerInPlace ->  toLowerInPlace/toLowercaseInPlace/toLowerCaseInPlace
toupper -> toUpper/toUppercase/toUpperCase
toupperInPlace -> toUpperInPlace/toUppercaseInPlace/toUpperCaseInPlace
tr -> replaceWithmModifiers
whitespace -> whitespaceCharsr
zfill -> zeroFill

-- 
/Jacob Carlborg

Andrei Alexandrescu Wrote:

> The following symbols in std.string don't satisfy the Phobos naming conventions and need to be renamed:
> 
> LS PS capwords countchars entab expandtabs hexdigits icmp iswhite ljustify lowercase maketrans newline octdigits removechars rjustify sformat splitlines stripl stripr tolower tolowerInPlace toupper toupperInPlace tr whitespace zfill
> 
> Opinions on what to rename?
> 
> 
> Thanks,
> 
> Andrei

A few notes:
A) As discussed already in the thread about Unicode, some string algorithms depend on locale/language. From what I see in the docs this isn't handled properly at the moment. Is it possible to remove/deprecate the functions or at least add a warning in the docs?
I prefer them to be marked as deprecated rather than renamed since they hopefully will be replaced anyway in the future.
B) I prefer trim over strip as it is more descriptive IMO:
stripl => leftTrim
stripr => rightTrim

strip sounds to me like something related to clothing.

On 01/21/2011 09:43 AM, Lutger Blijdestijn wrote:
> newline and whitespace: not sure how it is called in English, but these look
> like they have become single words and are fine.

I would not make such exceptions because there is no rational criterion to determine which multiple-word terms have become kinds of single-word terms, in english, AFAIK (eg: filename, dirname, drivename, fullname, shortname?). Anyway, D is not an english dialect, it just reuses the english lexicon.
Programmers would be left in constant doubt. Thus, the only practical scheme is a systematic rule: more-than-one-word ==> camel-case. It's more annoying to type, agreed, for common 2-words-only terms; but one can then always guess what the correct form is --without any doubt.
Also: very newcomer friendly.

Denis
_________________
vita es estrany
spir.wikidot.com

On 01/21/2011 09:43 AM, Lutger Blijdestijn wrote:
> LS and PS: since these are constants, upper case is ok, although LS is
> inconsistent with std.path.linesep.

Consistency across stdlib modules and with D builtin names (esp types) would be even more helpful than proper casing, imo.

[Also: Is there any chance to have a builtin name reform for Dn? This could be progressive: introduce builtin aliases --> deprecate non-conformant ones --> let conformant ones only.]

Denis
_________________
vita es estrany
spir.wikidot.com