Swift-style-guide: Naming convention for acronyms

[WingYn]

Maybe you should add a section for acronyms?

[gregheo]

What kind of acronyms? (Keeping in mind this is primarily a code rather than writing guide.)

[ghost]

@WingYn,

I'm going to close this issue based on the following:

1. If you're referring to acronyms in prose rather than code, then as Greg has mentioned this is not the correct place to discuss;
2. If you're referring to acronyms in code, then I believe this part of the guide has it covered:

Use descriptive names with camel case for classes, methods, variables, etc.

TL;DR: We don't advise using acronyms for naming anything in code.

Let me know if you were referring to some other kind of acronym.

[nicklockwood]

I believe it might be worth mentioning the case convention for acronyms, especially since this seems to have been formalized in Swift 3. Acronyms like URL or ID should never be mixed case, and whether they are upper or lower case depends on the position in the identifier:

Wrong:

var ID: String
var imageUrl: URL
typealias Id = String
typealias UniqueId = String

Right:

var id: String
var imageURL: URL
typealias ID = String
typealias UniqueID = String

[ssg]

agreed with @nicklockwood here. there are many interpretations of acronyms vs abbreviations etc. customerID or customerId? rawHTML or rawHtml? fileIO or fileIo?

[noamtamim]

"ID" is not an acronym. It's a short for "identifier" and should just be written id (or Id as a second word in a camelCase identifier).

[samwarfield]

I agree, but I have seen Apple use ID on NSManagedObjectID...

[JessyCatterwaul]

ID is not an acronym, but it is either a rare or unique form of initialism. The initials represent the first two syllables of "identification" or "identifier". It's a coincidence that the result looks exactly the same as an apocopation. If ID was an example of apocope, it would be a homophone of "eyed"; it actually is pronounced "eye dee".

All the letters in an acronym or initialism, per standardized Swift convention, use the same case. So, the only two forms to use are id and ID.

Id is one syllable with a short i: a word that is different than the two-syllable ID. But its lowerCamel form is a homograph with that of ID: id for both.

[JayantVarma]

There are so many repositories that have contributions from Java or DotNet devs (at work through out the years) that use Id as in CustomerId and worse still is in the API's. I don't know the grammar as well articulated as @JessyCatterwaul but I agree that it should be customerID it makes for clearer reading and is specific.

[rcritz]

I'm not going to reopen the issue because I believe Mic was correct in closing it and I believe the subsequent discussion is already addressed in the existing guide:

casing acronyms and initialisms uniformly up or down

in the Naming section. I may ~steal~ use nicklockwood's examples when I do the next guide update later this summer.

[dkk]

That convention seems rather strange to me when the acronym is in the middle. For example, would a function called parseURLScheme or testHTTPConnection be ok? or even parseHTTPURLDomain? it looks way less readable than parseUrlScheme or testHttpConnection or parseHttpUrlDomain. Or is there also a rule against having acronyms in the middle while naming? or is this just not being taken into consideration?

[JessyCatterwaul]

I don't disagree about the readability, @dkk. I actually don't think any of the options are good. ☹️ I think the Swift convention has come at least somewhat from historical precedent. At least they picked one!

[rcritz]

I actually do disagree about readability. I think, in addition to being closer to Apple's naming, the fact that it matches how one writes English — and how we require our authors to write — is helpful.

[dkk]

@rcritz I don't think that you can compare it to normal writing, since we don't use whitespaces. But I agree with @JessyCatterwaul about the historical value. The problem is that in practice, you usually don't just have technologies such as BLE, URL and HTTP like Apple's APIs. At least in the projects in which I have participated, more often than not, you have acronyms for backend services, specific databases, branches of the company, countries, world regions, etc., which almost always leads to very strange looking variables and functions if you follow this convention. And in my experience, many projects make an exception out of this rule. But it may be coincidence, maybe we could make a statistic out of swift projects in github to try to find out if most people think that it makes sense or if they ignore it. I'll try to write a parser and collect some data about it if I have time.

[rcritz]

@dkk remember that this style guide is specifically for us as a tutorial/book team so not only can you compare it to writing English, you must do so.

[asreerama]

https://swift.org/documentation/api-design-guidelines/#general-conventions