Case conventions for mixed-case words (like "iPad" and "NaN")

Evolution Discussion
1

Hi, everyone. Today in the API Design Guidelines <https://swift.org/documentation/api-design-guidelines/&gt; we have this section on case:

Follow case conventions. Names of types and protocols are UpperCamelCase. Everything else is lowerCamelCase.

Acronyms and initialisms that commonly appear as all upper case in American English should be uniformly up- or down-cased according to case conventions:

var utf8Bytes: [UTF8.CodeUnit]
var isRepresentableAsASCII = true
var userSMTPServer: SecureSMTPServer

Other acronyms should be treated as ordinary words:

var radarDetector: RadarScanner
var enjoysScubaDiving = true

However, this doesn't directly address words that are conventionally written with mixed case. Usually these are names, such as "iPad", "LaTeX", or “NeXT”, but sometimes they’re just acronyms or initialisms with very strong conventions, like “NaN”. (Yes, the FloatingPoint proposal is what prompted this whole thing.)

There are a few options for what we could do with these words to make them consistent with our existing rules for words that are all-uppercase, all-lowercase, or capitalized (first letter uppercase, remaining letters lowercase). It’s pretty clear from the “utf8Bytes” example above that use at the start of a “lowerCamelCase” identifier means uniformly downcasing all of the letters: “ipad”, “latex”, “next”, “nan”. However, it’s unclear exactly what operation is being applied to subsequent words in an identifier:

Option 1: Upcase the first letter, leave all the other letters alone. This is consistent with all of the examples shown in the API design guidelines, and produces “IPad”, “LaTeX”, “NeXT”, and “NaN”. (In context, that might be “supportsIPad”, “LaTeXRenderer”, “isNeXTPlatform”, and “signalingNaN”, alongside “ipadIcon”, “latexSource”, “nextLogo”, and “nanValue”.)

Option 2: If any letters are lowercase, upcase the first letter and downcase all other letters. This is also consistent with all of the examples shown in the API design guidelines, and produces “Ipad”, “Latex”, “Next”, and “Nan”. (In context, that’s “supportsIpad”, “LatexRenderer”, “isNextPlatform”, and “signalingNan”, alongside “ipadIcon”, “latexSource”, “nextLogo”, and “nanValue”.)

I prefer option 1 because I think it’s easier to recognize the original form of the word; DaveA notes that under option 2 it’s easier to find the word boundaries.

(“NeXT” is an especially tricky case because without case it’s not distinguishable from the normal word “next”. This situation is rare but not nonexistent. Then again, “Apple” is not distinguishable from the normal word “apple” either, and we seem to do fine there.)

Thoughts?
Jordan

P.S. The rules also don’t special-case all-lowercase initialisms, like “mph” (for “miles per hour”). Under either option above, we’d get “Mph”. If we want some other behavior,

2

[resending to include list]

Hm. I’m not sure why these words would be special, though—if we were going to use underscores, shouldn’t we consistently go for “snake_case” or something?

(A leading underscore is also often used to denote something private in a lot of conventions, including the standard library.)

Jordan

···

On May 5, 2016, at 08:38, Basem Emara <contact@basememara.com <mailto:contact@basememara.com>> wrote:

Indeed the scenario has always been tricky for conventions. In both option 1 and 2, it looses the meaning, so I propose option 3 (which still sux too ha):

Option 3: Surround with underscores to isolate the acronym with mixed casing. It clearly retains the original meaning since acronys already create ambigiouty. An added degree of ambiguity could lose it’s meaning complete. This way with underscores, it is clear what it is referring to. In context, that might be “supports_iPad”, “_LaTeX_Renderer”, “is_NeXT_Platform”, and “signaling_NaN”, alongside “_iPad_Icon”, “_LaTeX_Source”, “_NeXT_Logo”, and “_NaN_Value”.)

On May 5, 2016, at 11:26 AM, Jordan Rose via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

Hi, everyone. Today in the API Design Guidelines <https://swift.org/documentation/api-design-guidelines/&gt; we have this section on case:

Follow case conventions. Names of types and protocols are UpperCamelCase. Everything else is lowerCamelCase.

Acronyms and initialisms that commonly appear as all upper case in American English should be uniformly up- or down-cased according to case conventions:

var utf8Bytes: [UTF8.CodeUnit]
var isRepresentableAsASCII = true
var userSMTPServer: SecureSMTPServer

Other acronyms should be treated as ordinary words:

var radarDetector: RadarScanner
var enjoysScubaDiving = true

However, this doesn't directly address words that are conventionally written with mixed case. Usually these are names, such as "iPad", "LaTeX", or “NeXT”, but sometimes they’re just acronyms or initialisms with very strong conventions, like “NaN”. (Yes, the FloatingPoint proposal is what prompted this whole thing.)

There are a few options for what we could do with these words to make them consistent with our existing rules for words that are all-uppercase, all-lowercase, or capitalized (first letter uppercase, remaining letters lowercase). It’s pretty clear from the “utf8Bytes” example above that use at the start of a “lowerCamelCase” identifier means uniformly downcasing all of the letters: “ipad”, “latex”, “next”, “nan”. However, it’s unclear exactly what operation is being applied to subsequent words in an identifier:

Option 1: Upcase the first letter, leave all the other letters alone. This is consistent with all of the examples shown in the API design guidelines, and produces “IPad”, “LaTeX”, “NeXT”, and “NaN”. (In context, that might be “supportsIPad”, “LaTeXRenderer”, “isNeXTPlatform”, and “signalingNaN”, alongside “ipadIcon”, “latexSource”, “nextLogo”, and “nanValue”.)

Option 2: If any letters are lowercase, upcase the first letter and downcase all other letters. This is also consistent with all of the examples shown in the API design guidelines, and produces “Ipad”, “Latex”, “Next”, and “Nan”. (In context, that’s “supportsIpad”, “LatexRenderer”, “isNextPlatform”, and “signalingNan”, alongside “ipadIcon”, “latexSource”, “nextLogo”, and “nanValue”.)

I prefer option 1 because I think it’s easier to recognize the original form of the word; DaveA notes that under option 2 it’s easier to find the word boundaries.

(“NeXT” is an especially tricky case because without case it’s not distinguishable from the normal word “next”. This situation is rare but not nonexistent. Then again, “Apple” is not distinguishable from the normal word “apple” either, and we seem to do fine there.)

Thoughts?
Jordan

P.S. The rules also don’t special-case all-lowercase initialisms, like “mph” (for “miles per hour”). Under either option above, we’d get “Mph”. If we want some other behavior,
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

3

“Apple” isn’t the name of a common function for dealing with collections & sequences.

“NeXT” is probably rare enough that we could keep it as-written regardless of whatever we settle on for the rest. Personally, I prefer to use the correct (that is, whatever you’d normally use in written communication) camel case, capitalizing the first letter when necessary (such as “foo.isIPad”) and not bother worrying about it more than that unless doing so would make for an ambiguous name.

That said, I’ve never tried to take part in defining standard library naming conventions before... There’s a fair chance I’m not seeing an obvious problem, rather than merely disagreeing.

- Dave Sweeris

···

On May 5, 2016, at 10:26 AM, Jordan Rose via swift-evolution <swift-evolution@swift.org> wrote:

(“NeXT” is an especially tricky case because without case it’s not distinguishable from the normal word “next”. This situation is rare but not nonexistent. Then again, “Apple” is not distinguishable from the normal word “apple” either, and we seem to do fine there.)

4

I think ipad and IPAD are better. Ipad and IPad look really bad.
e.g isIPAD / ipadUser / isNAN / nan

Or what about this: For lowerCamelCase, we use all lower letters (like ipad).
For UpperCamelCase, we keep the original one (iPad).
e.g. isiPad / ipadUser isNaN / nan

Justin

5

[resending to include list]

Hm. I’m not sure why these words would be special, though—if we were going to use underscores, shouldn’t we consistently go for “snake_case” or something?

+1. Mixing the two is just ugly IMO. I prefer snake case to camel case in general but it seems way too late to make that change in Swift now even if we wanted to and it would complicate import of Objective-C.

···

Sent from my iPad

On May 5, 2016, at 10:41 AM, Jordan Rose via swift-evolution <swift-evolution@swift.org> wrote:

(A leading underscore is also often used to denote something private in a lot of conventions, including the standard library.)

Jordan

On May 5, 2016, at 08:38, Basem Emara <contact@basememara.com> wrote:

Indeed the scenario has always been tricky for conventions. In both option 1 and 2, it looses the meaning, so I propose option 3 (which still sux too ha):

Option 3: Surround with underscores to isolate the acronym with mixed casing. It clearly retains the original meaning since acronys already create ambigiouty. An added degree of ambiguity could lose it’s meaning complete. This way with underscores, it is clear what it is referring to. In context, that might be “supports_iPad”, “_LaTeX_Renderer”, “is_NeXT_Platform”, and “signaling_NaN”, alongside “_iPad_Icon”, “_LaTeX_Source”, “_NeXT_Logo”, and “_NaN_Value”.)

On May 5, 2016, at 11:26 AM, Jordan Rose via swift-evolution <swift-evolution@swift.org> wrote:

Hi, everyone. Today in the API Design Guidelines we have this section on case:

Follow case conventions. Names of types and protocols are UpperCamelCase. Everything else is lowerCamelCase.

Acronyms and initialisms that commonly appear as all upper case in American English should be uniformly up- or down-cased according to case conventions:

var utf8Bytes: [UTF8.CodeUnit]
var isRepresentableAsASCII = true
var userSMTPServer: SecureSMTPServer

Other acronyms should be treated as ordinary words:

var radarDetector: RadarScanner
var enjoysScubaDiving = true

However, this doesn't directly address words that are conventionally written with mixed case. Usually these are names, such as "iPad", "LaTeX", or “NeXT”, but sometimes they’re just acronyms or initialisms with very strong conventions, like “NaN”. (Yes, the FloatingPoint proposal is what prompted this whole thing.)

There are a few options for what we could do with these words to make them consistent with our existing rules for words that are all-uppercase, all-lowercase, or capitalized (first letter uppercase, remaining letters lowercase). It’s pretty clear from the “utf8Bytes” example above that use at the start of a “lowerCamelCase” identifier means uniformly downcasing all of the letters: “ipad”, “latex”, “next”, “nan”. However, it’s unclear exactly what operation is being applied to subsequent words in an identifier:

Option 1: Upcase the first letter, leave all the other letters alone. This is consistent with all of the examples shown in the API design guidelines, and produces “IPad”, “LaTeX”, “NeXT”, and “NaN”. (In context, that might be “supportsIPad”, “LaTeXRenderer”, “isNeXTPlatform”, and “signalingNaN”, alongside “ipadIcon”, “latexSource”, “nextLogo”, and “nanValue”.)

Option 2: If any letters are lowercase, upcase the first letter and downcase all other letters. This is also consistent with all of the examples shown in the API design guidelines, and produces “Ipad”, “Latex”, “Next”, and “Nan”. (In context, that’s “supportsIpad”, “LatexRenderer”, “isNextPlatform”, and “signalingNan”, alongside “ipadIcon”, “latexSource”, “nextLogo”, and “nanValue”.)

I prefer option 1 because I think it’s easier to recognize the original form of the word; DaveA notes that under option 2 it’s easier to find the word boundaries.

(“NeXT” is an especially tricky case because without case it’s not distinguishable from the normal word “next”. This situation is rare but not nonexistent. Then again, “Apple” is not distinguishable from the normal word “apple” either, and we seem to do fine there.)

Thoughts?
Jordan

P.S. The rules also don’t special-case all-lowercase initialisms, like “mph” (for “miles per hour”). Under either option above, we’d get “Mph”. If we want some other behavior,
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

6

Yes I digress and agree with you consistency is absolute key. Another thought came to mind:

Option 3 3: Uppercase all acronyms including those with mixed casing. This is both consistent and clear. Isolating acronyms is important because they loose their meaning and bleed into word boundaries, so making even mixed acronyms all uppercase clearly identifies them. In context, that might be “supportsIPAD”, “LATEXRenderer”, “isNEXTPlatform”, and “signalingNAN”, alongside “IPADIcon”, “LATEXSource”, “NEXTLogo”, and “NANValue”.)

···

On May 5, 2016, at 11:41 AM, Jordan Rose <jordan_rose@apple.com> wrote:

[resending to include list]

Hm. I’m not sure why these words would be special, though—if we were going to use underscores, shouldn’t we consistently go for “snake_case” or something?

(A leading underscore is also often used to denote something private in a lot of conventions, including the standard library.)

Jordan

On May 5, 2016, at 08:38, Basem Emara <contact@basememara.com <mailto:contact@basememara.com>> wrote:

Indeed the scenario has always been tricky for conventions. In both option 1 and 2, it looses the meaning, so I propose option 3 (which still sux too ha):

Option 3: Surround with underscores to isolate the acronym with mixed casing. It clearly retains the original meaning since acronys already create ambigiouty. An added degree of ambiguity could lose it’s meaning complete. This way with underscores, it is clear what it is referring to. In context, that might be “supports_iPad”, “_LaTeX_Renderer”, “is_NeXT_Platform”, and “signaling_NaN”, alongside “_iPad_Icon”, “_LaTeX_Source”, “_NeXT_Logo”, and “_NaN_Value”.)

On May 5, 2016, at 11:26 AM, Jordan Rose via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

Hi, everyone. Today in the API Design Guidelines <https://swift.org/documentation/api-design-guidelines/&gt; we have this section on case:

Follow case conventions. Names of types and protocols are UpperCamelCase. Everything else is lowerCamelCase.

Acronyms and initialisms that commonly appear as all upper case in American English should be uniformly up- or down-cased according to case conventions:

var utf8Bytes: [UTF8.CodeUnit]
var isRepresentableAsASCII = true
var userSMTPServer: SecureSMTPServer

Other acronyms should be treated as ordinary words:

var radarDetector: RadarScanner
var enjoysScubaDiving = true

However, this doesn't directly address words that are conventionally written with mixed case. Usually these are names, such as "iPad", "LaTeX", or “NeXT”, but sometimes they’re just acronyms or initialisms with very strong conventions, like “NaN”. (Yes, the FloatingPoint proposal is what prompted this whole thing.)

There are a few options for what we could do with these words to make them consistent with our existing rules for words that are all-uppercase, all-lowercase, or capitalized (first letter uppercase, remaining letters lowercase). It’s pretty clear from the “utf8Bytes” example above that use at the start of a “lowerCamelCase” identifier means uniformly downcasing all of the letters: “ipad”, “latex”, “next”, “nan”. However, it’s unclear exactly what operation is being applied to subsequent words in an identifier:

Option 1: Upcase the first letter, leave all the other letters alone. This is consistent with all of the examples shown in the API design guidelines, and produces “IPad”, “LaTeX”, “NeXT”, and “NaN”. (In context, that might be “supportsIPad”, “LaTeXRenderer”, “isNeXTPlatform”, and “signalingNaN”, alongside “ipadIcon”, “latexSource”, “nextLogo”, and “nanValue”.)

Option 2: If any letters are lowercase, upcase the first letter and downcase all other letters. This is also consistent with all of the examples shown in the API design guidelines, and produces “Ipad”, “Latex”, “Next”, and “Nan”. (In context, that’s “supportsIpad”, “LatexRenderer”, “isNextPlatform”, and “signalingNan”, alongside “ipadIcon”, “latexSource”, “nextLogo”, and “nanValue”.)

I prefer option 1 because I think it’s easier to recognize the original form of the word; DaveA notes that under option 2 it’s easier to find the word boundaries.

(“NeXT” is an especially tricky case because without case it’s not distinguishable from the normal word “next”. This situation is rare but not nonexistent. Then again, “Apple” is not distinguishable from the normal word “apple” either, and we seem to do fine there.)

Thoughts?
Jordan

P.S. The rules also don’t special-case all-lowercase initialisms, like “mph” (for “miles per hour”). Under either option above, we’d get “Mph”. If we want some other behavior,
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

7

NaN is really a problem only because of using it as an acronym rather than just having .invalidNumber or .notANumber (little uglier) or something similar instead. This comes back to the annoying consideration between something being prior art, at the cost of potentially defining something that’s better, or a better fit for the language. If NaN didn’t exist elsewhere, would we even consider it at all if we were implementing float point numbers for the first ever time in Swift? I’d prefer we defined something more verbose as an alternative to avoid the acronym entirely.

When it comes to having iPad conformance the question is; should we ever actually test for names at all? An iPad is a brand, it’s not really something that a program should test for, as what’s important to a program are capabilities. The same is true with testing for an OS, we don’t want to test Windows, Mac etc., but rather to test what libraries are available. Same is true with hardware; it doesn’t matter if a device is an iPad, what matters is that it has a touch-screen rather than a keyboard, that it has a small screen rather than a full monitor, that it’s mobile (and not plugged in) etc.
Testing for names like that should be avoided at all costs when it comes to variable and method names, and be relegated to string-based tests for when you absolutely have to access that information. In other words programs should be platform agnostic, and only need to know whether capabilities they require or optionally support exist or not.
For these I’d prefer that the guidelines warn against these in the strongest possible terms, as they’re usually a bad idea IMO.

···

On 5 May 2016, at 20:49, Justin Jia via swift-evolution <swift-evolution@swift.org> wrote:

I think ipad and IPAD are better. Ipad and IPad look really bad.
e.g isIPAD / ipadUser / isNAN / nan

Or what about this: For lowerCamelCase, we use all lower letters (like ipad).
For UpperCamelCase, we keep the original one (iPad).
e.g. isiPad / ipadUser isNaN / nan

Justin

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

8

Terminology-wise, most of these are not acronyms <acronym - Wiktionary, the free dictionary; (or initialisms <initialism - Wiktionary, the free dictionary), but you’re right that that’s a third option consistent with the existing guidelines.

Jordan

···

On May 5, 2016, at 08:56, Basem Emara <contact@basememara.com> wrote:

Yes I digress and agree with you consistency is absolute key. Another thought came to mind:

Option 3 3: Uppercase all acronyms including those with mixed casing. This is both consistent and clear. Isolating acronyms is important because they loose their meaning and bleed into word boundaries, so making even mixed acronyms all uppercase clearly identifies them. In context, that might be “supportsIPAD”, “LATEXRenderer”, “isNEXTPlatform”, and “signalingNAN”, alongside “IPADIcon”, “LATEXSource”, “NEXTLogo”, and “NANValue”.)

On May 5, 2016, at 11:41 AM, Jordan Rose <jordan_rose@apple.com <mailto:jordan_rose@apple.com>> wrote:

[resending to include list]

Hm. I’m not sure why these words would be special, though—if we were going to use underscores, shouldn’t we consistently go for “snake_case” or something?

(A leading underscore is also often used to denote something private in a lot of conventions, including the standard library.)

Jordan

On May 5, 2016, at 08:38, Basem Emara <contact@basememara.com <mailto:contact@basememara.com>> wrote:

Indeed the scenario has always been tricky for conventions. In both option 1 and 2, it looses the meaning, so I propose option 3 (which still sux too ha):

Option 3: Surround with underscores to isolate the acronym with mixed casing. It clearly retains the original meaning since acronys already create ambigiouty. An added degree of ambiguity could lose it’s meaning complete. This way with underscores, it is clear what it is referring to. In context, that might be “supports_iPad”, “_LaTeX_Renderer”, “is_NeXT_Platform”, and “signaling_NaN”, alongside “_iPad_Icon”, “_LaTeX_Source”, “_NeXT_Logo”, and “_NaN_Value”.)

On May 5, 2016, at 11:26 AM, Jordan Rose via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

Hi, everyone. Today in the API Design Guidelines <https://swift.org/documentation/api-design-guidelines/&gt; we have this section on case:

Follow case conventions. Names of types and protocols are UpperCamelCase. Everything else is lowerCamelCase.

Acronyms and initialisms that commonly appear as all upper case in American English should be uniformly up- or down-cased according to case conventions:

var utf8Bytes: [UTF8.CodeUnit]
var isRepresentableAsASCII = true
var userSMTPServer: SecureSMTPServer

Other acronyms should be treated as ordinary words:

var radarDetector: RadarScanner
var enjoysScubaDiving = true

However, this doesn't directly address words that are conventionally written with mixed case. Usually these are names, such as "iPad", "LaTeX", or “NeXT”, but sometimes they’re just acronyms or initialisms with very strong conventions, like “NaN”. (Yes, the FloatingPoint proposal is what prompted this whole thing.)

There are a few options for what we could do with these words to make them consistent with our existing rules for words that are all-uppercase, all-lowercase, or capitalized (first letter uppercase, remaining letters lowercase). It’s pretty clear from the “utf8Bytes” example above that use at the start of a “lowerCamelCase” identifier means uniformly downcasing all of the letters: “ipad”, “latex”, “next”, “nan”. However, it’s unclear exactly what operation is being applied to subsequent words in an identifier:

Option 1: Upcase the first letter, leave all the other letters alone. This is consistent with all of the examples shown in the API design guidelines, and produces “IPad”, “LaTeX”, “NeXT”, and “NaN”. (In context, that might be “supportsIPad”, “LaTeXRenderer”, “isNeXTPlatform”, and “signalingNaN”, alongside “ipadIcon”, “latexSource”, “nextLogo”, and “nanValue”.)

Option 2: If any letters are lowercase, upcase the first letter and downcase all other letters. This is also consistent with all of the examples shown in the API design guidelines, and produces “Ipad”, “Latex”, “Next”, and “Nan”. (In context, that’s “supportsIpad”, “LatexRenderer”, “isNextPlatform”, and “signalingNan”, alongside “ipadIcon”, “latexSource”, “nextLogo”, and “nanValue”.)

I prefer option 1 because I think it’s easier to recognize the original form of the word; DaveA notes that under option 2 it’s easier to find the word boundaries.

(“NeXT” is an especially tricky case because without case it’s not distinguishable from the normal word “next”. This situation is rare but not nonexistent. Then again, “Apple” is not distinguishable from the normal word “apple” either, and we seem to do fine there.)

Thoughts?
Jordan

P.S. The rules also don’t special-case all-lowercase initialisms, like “mph” (for “miles per hour”). Under either option above, we’d get “Mph”. If we want some other behavior,
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

9

Whether using the word iPad is wise or not, the question still remains what
to do when encountering a term that looks like that. If I'm writing an app
that deals with chemical compounds, how should I name a type that deals
with pH? How about a computed property representing pH? Should either or
both be PH, pH, or ph? It certainly will not do to say "just name it
powerOfHydrogen".

···

On Thu, May 5, 2016 at 5:31 PM, Haravikk via swift-evolution < swift-evolution@swift.org> wrote:

NaN is really a problem only because of using it as an acronym rather than
just having .invalidNumber or .notANumber (little uglier) or something
similar instead. This comes back to the annoying consideration between
something being prior art, at the cost of potentially defining something
that’s better, or a better fit for the language. If NaN didn’t exist
elsewhere, would we even consider it at all if we were implementing float
point numbers for the first ever time in Swift? I’d prefer we defined
something more verbose as an alternative to avoid the acronym entirely.

When it comes to having iPad conformance the question is; should we ever
actually test for names at all? An iPad is a brand, it’s not really
something that a program should test for, as what’s important to a program
are capabilities. The same is true with testing for an OS, we don’t want to
test Windows, Mac etc., but rather to test what libraries are available.
Same is true with hardware; it doesn’t matter if a device is an iPad, what
matters is that it has a touch-screen rather than a keyboard, that it has a
small screen rather than a full monitor, that it’s mobile (and not plugged
in) etc.
Testing for names like that should be avoided at all costs when it comes
to variable and method names, and be relegated to string-based tests for
when you absolutely have to access that information. In other words
programs should be platform agnostic, and only need to know whether
capabilities they require or optionally support exist or not.
For these I’d prefer that the guidelines warn against these in the
strongest possible terms, as they’re usually a bad idea IMO.

10

Right, stating that you don’t like these particular examples or terms of art doesn’t change the need for a proper convention. There will be cases where a term of art is the right thing to use, and that term happens to be conventionally spelled with mixed case. The point of naming guidelines is to provide an answer when the situation does arise; right now they’re ambiguous.

Jordan

···

On May 5, 2016, at 15:54, Xiaodi Wu via swift-evolution <swift-evolution@swift.org> wrote:

On Thu, May 5, 2016 at 5:31 PM, Haravikk via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
NaN is really a problem only because of using it as an acronym rather than just having .invalidNumber or .notANumber (little uglier) or something similar instead. This comes back to the annoying consideration between something being prior art, at the cost of potentially defining something that’s better, or a better fit for the language. If NaN didn’t exist elsewhere, would we even consider it at all if we were implementing float point numbers for the first ever time in Swift? I’d prefer we defined something more verbose as an alternative to avoid the acronym entirely.

When it comes to having iPad conformance the question is; should we ever actually test for names at all? An iPad is a brand, it’s not really something that a program should test for, as what’s important to a program are capabilities. The same is true with testing for an OS, we don’t want to test Windows, Mac etc., but rather to test what libraries are available. Same is true with hardware; it doesn’t matter if a device is an iPad, what matters is that it has a touch-screen rather than a keyboard, that it has a small screen rather than a full monitor, that it’s mobile (and not plugged in) etc.
Testing for names like that should be avoided at all costs when it comes to variable and method names, and be relegated to string-based tests for when you absolutely have to access that information. In other words programs should be platform agnostic, and only need to know whether capabilities they require or optionally support exist or not.
For these I’d prefer that the guidelines warn against these in the strongest possible terms, as they’re usually a bad idea IMO.

Whether using the word iPad is wise or not, the question still remains what to do when encountering a term that looks like that. If I'm writing an app that deals with chemical compounds, how should I name a type that deals with pH? How about a computed property representing pH? Should either or both be PH, pH, or ph? It certainly will not do to say "just name it powerOfHydrogen”.

11

I would support Option 3. Neither iPad nor NeXT are acronyms, so they needn’t fall under the same rule.

Rule A: Acronyms
all lowercase, all uppercase
URL -> urlString, URLRequest
LaTeX -> latexSource, LATEXRenderer
GIF -> gifRepresentation, GIFGenerator

Rule B: Brand names
all lowercase, first uppercase and rest as usual
iPad -> ipadIcon, IPadDevices
NeXT -> nextIcon, NeXTCompany
LinkedIn -> linkedinIcon, LinkedInCompany

Now you might argue that LaTeX is a brand name, so perhaps it should fall under rule B. Deciding whether something is an acronym or a brand name can evolve over time, and is something that should lay outside the naming guidelines I think. In the same way radar and scuba have become normal words, they are decided by culture.

···

On 6 May 2016, at 3:09 AM, Jordan Rose via swift-evolution <swift-evolution@swift.org> wrote:

Terminology-wise, most of these are not acronyms <acronym - Wiktionary, the free dictionary; (or initialisms <initialism - Wiktionary, the free dictionary), but you’re right that that’s a third option consistent with the existing guidelines.

Jordan

On May 5, 2016, at 08:56, Basem Emara <contact@basememara.com <mailto:contact@basememara.com>> wrote:

Yes I digress and agree with you consistency is absolute key. Another thought came to mind:

Option 3 3: Uppercase all acronyms including those with mixed casing. This is both consistent and clear. Isolating acronyms is important because they loose their meaning and bleed into word boundaries, so making even mixed acronyms all uppercase clearly identifies them. In context, that might be “supportsIPAD”, “LATEXRenderer”, “isNEXTPlatform”, and “signalingNAN”, alongside “IPADIcon”, “LATEXSource”, “NEXTLogo”, and “NANValue”.)

On May 5, 2016, at 11:41 AM, Jordan Rose <jordan_rose@apple.com <mailto:jordan_rose@apple.com>> wrote:

[resending to include list]

Hm. I’m not sure why these words would be special, though—if we were going to use underscores, shouldn’t we consistently go for “snake_case” or something?

(A leading underscore is also often used to denote something private in a lot of conventions, including the standard library.)

Jordan

On May 5, 2016, at 08:38, Basem Emara <contact@basememara.com <mailto:contact@basememara.com>> wrote:

Indeed the scenario has always been tricky for conventions. In both option 1 and 2, it looses the meaning, so I propose option 3 (which still sux too ha):

Option 3: Surround with underscores to isolate the acronym with mixed casing. It clearly retains the original meaning since acronys already create ambigiouty. An added degree of ambiguity could lose it’s meaning complete. This way with underscores, it is clear what it is referring to. In context, that might be “supports_iPad”, “_LaTeX_Renderer”, “is_NeXT_Platform”, and “signaling_NaN”, alongside “_iPad_Icon”, “_LaTeX_Source”, “_NeXT_Logo”, and “_NaN_Value”.)

On May 5, 2016, at 11:26 AM, Jordan Rose via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

Hi, everyone. Today in the API Design Guidelines <https://swift.org/documentation/api-design-guidelines/&gt; we have this section on case:

Follow case conventions. Names of types and protocols are UpperCamelCase. Everything else is lowerCamelCase.

Acronyms and initialisms that commonly appear as all upper case in American English should be uniformly up- or down-cased according to case conventions:

var utf8Bytes: [UTF8.CodeUnit]
var isRepresentableAsASCII = true
var userSMTPServer: SecureSMTPServer

Other acronyms should be treated as ordinary words:

var radarDetector: RadarScanner
var enjoysScubaDiving = true

However, this doesn't directly address words that are conventionally written with mixed case. Usually these are names, such as "iPad", "LaTeX", or “NeXT”, but sometimes they’re just acronyms or initialisms with very strong conventions, like “NaN”. (Yes, the FloatingPoint proposal is what prompted this whole thing.)

There are a few options for what we could do with these words to make them consistent with our existing rules for words that are all-uppercase, all-lowercase, or capitalized (first letter uppercase, remaining letters lowercase). It’s pretty clear from the “utf8Bytes” example above that use at the start of a “lowerCamelCase” identifier means uniformly downcasing all of the letters: “ipad”, “latex”, “next”, “nan”. However, it’s unclear exactly what operation is being applied to subsequent words in an identifier:

Option 1: Upcase the first letter, leave all the other letters alone. This is consistent with all of the examples shown in the API design guidelines, and produces “IPad”, “LaTeX”, “NeXT”, and “NaN”. (In context, that might be “supportsIPad”, “LaTeXRenderer”, “isNeXTPlatform”, and “signalingNaN”, alongside “ipadIcon”, “latexSource”, “nextLogo”, and “nanValue”.)

Option 2: If any letters are lowercase, upcase the first letter and downcase all other letters. This is also consistent with all of the examples shown in the API design guidelines, and produces “Ipad”, “Latex”, “Next”, and “Nan”. (In context, that’s “supportsIpad”, “LatexRenderer”, “isNextPlatform”, and “signalingNan”, alongside “ipadIcon”, “latexSource”, “nextLogo”, and “nanValue”.)

I prefer option 1 because I think it’s easier to recognize the original form of the word; DaveA notes that under option 2 it’s easier to find the word boundaries.

(“NeXT” is an especially tricky case because without case it’s not distinguishable from the normal word “next”. This situation is rare but not nonexistent. Then again, “Apple” is not distinguishable from the normal word “apple” either, and we seem to do fine there.)

Thoughts?
Jordan

P.S. The rules also don’t special-case all-lowercase initialisms, like “mph” (for “miles per hour”). Under either option above, we’d get “Mph”. If we want some other behavior,
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution