Change camel case acronym rules

[teradyl]

Summary

This would update the style guide to treat acronyms as normal words within camel case.

No matter what happens, I'll work on a linter rule so we can keep things consistent.

Please read the reasoning below and mark with 👍/👎

Reasoning

Pros:

• Easier transitioning between snake_case (from the server and from Codable models) and camelCase because every word is consistent without exception. This way we won't have to write special code or have an acronym whitelist to to convert variables with acronyms in them.
• Potentially better for GraphQL variable conversion in the future.
• Argument for readability: Easier to mentally separate the words with no all caps acronyms running into the next word. For examples: httpURLRequest vs httpUrlRequest
• We won't be the only ones: Google's Java style guide does this https://google.github.io/styleguide/javaguide.html#s5.3-camel-case

Cons:

• This isn't how Apple treats acronyms in camelCase (https://swift.org/documentation/api-design-guidelines/#general-conventions)
• Mental overhead of thinking about what name something should be depending on whether it's defined by Apple or Airbnb
• Argument for readability: Acronyms in real English are in fact all caps

Reviewers

cc @airbnb/swift-styleguide-maintainers

Please react with 👍/👎 if you agree or disagree with this proposal.

[ljharb]

In the JS guide, we’ve explicitly chosen to always capitalize or lowercase acronyms and initialisms, because we have no need to cleave to a camelCasing algorithm designed to make life easier for machines, and we prefer names to make more sense for humans.

[teradyl]

@ljharb Thanks for the feedback. I actually think that this new way of doing things is easier for humans as well. There are lots of ambiguities regarding acronyms and camel case that will be gone if we use TrueCamelCase. Along with the lack of spaces cases mentioned in the original description, here are some examples:

Examples:

1. Plural acronyms are confusing.
   Is it linkURLs vs linkUrls or is it linkURLS? What do we do with the s?
   userIDsToDelete vs userIdsToDelete is another one.

2. Blended acronyms that happen one after another are also difficult to read.
   isSMTPSSLRequired is much more difficult to read than isSmtpSslRequired.

I think the new rule is superior in terms of readability, and not to mention the fact that code is easier to read when we don't have to write extra rules to make it easier for the machine to understand it as well.

On Apple's own Swift rules it says that everything is UpperCamelCase or lowerCamelCase and then they have 2 extra paragraphs detailing all the possible exceptions with acronyms. If we lose all the capital acronyms we also do away with all exceptions so that everything is proper camel case.

[bachand]

I'd also like to include this screenshot from the official Swift API Design Guidelines.

One of the guiding tenets of the style guide is:

This guide is in addition to the official Swift API Design Guidelines. These rules should not contradict that document.

This change would contradict the Swift API Design Guidelines.

[teradyl]

@bachand While I think we should follow the Swift API Design Guidelines as much as possible, when many signs of human readability & machine processing point in a new direction, I don't think we should let those guidelines hold us back.

As I mentioned above, if we adopt this new rule we won't have any ambiguous exceptions to our camel case variables and the rule will be one sentence.

[jqsilver]

@bachand I feel like that screenshot proves @teradyl 's point that apple's guidelines are actually weirdly inconsistent. I'm not sure like "commonly appear in American english" as a guideline since it basically requires us maintaining a dictionary of acronyms and how they should appear.

[jqsilver]

How easy would it be to exempt code defined by an external API from our style guide? Could we say "use all caps acronyms except when required by an external API"?

[bachand]

In my mind I don’t view Apple’s rule as inconsistent. All things being equal I would prefer a rule that didn’t have exceptions. However I also think that the exceptions in this case seem well-reasoned and easy to follow 🤷‍♂️

[gonzalonunez]

Seems to me like the primary conflict here has to do with the naming conventions of different languages, and it feels wrong to me to allow the naming conventions of one language to influence those of another. I don't think we should be considering languages that use snake_case, GraphQL, or Java when making a decision about our naming conventions in Swift.

IMO, the conventions outlined in the Swift API Design Guidelines result in the most elegant and readable Swift.

[bachand]

@jqsilver do you think we would want to add a guideline like that at the top level of the guide? I can see external frameworks / API requiring us to deviate from other style rules as well.

[jqsilver]

Okay, I’ve been convinced that we shouldn’t let other languages or api conventions define our style (besides swift and cocoa). I think if we could just organize our code so that we easily exempt certain files then I’d be satisfied.

…

On Thu, Jan 10, 2019 at 2:59 PM Michael Bachand ***@***.***> wrote: @jqsilver <https://github.com/jqsilver> do you think we would want to add a guideline like that at the top level of the guide? I can see external frameworks / API requiring us to deviate from other style rules as well. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#37 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACP_SrJUkWI8njwD1u5prLHWdpBpIrNRks5vB8W4gaJpZM4Z6Ja1> .

[gilbox]

I voted yes but only because of Codable. Even though there are some edge cases as pointed out above where camel casing is more readable, Imo camel casing acronyms is generally less readable because I'm used to seeing acronyms uppercased.

[gonzalonunez]

I'm pretty optimistic about being able to implement simple, performant .custom([CodingKey]) -> CodingKey) encoding and decoding strategies that convert to/from snake case as well as handle the acronym exceptions that we'd like to cover.

If we're unable to do this successfully or we deem the cost of this to be too high (performance, maintenance, safety, etc.), then I'd be happy with organizing our code to allow for exceptions for Codable models.

[bryankeller]

I would really, really like to stick with Apple's approach here, and keep acronyms uppercase. If most / all of Apple's Apis are following one convention, I don't like us deviating from that (for consistency reasons).

Also, capitalizing acronyms conveys something extra - that this is an acronym, which becomes much less obvious if I need to read it like a word first, then backtrack to figure out if it's actually an acronym.

Easier transitioning between snake_case (from the server and from Codable models) and camelCase because every word is consistent without exception. This way we won't have to write special code or have an acronym whitelist to to convert variables with acronyms in them.

This is a hardly pain point in my life. I'd value consistency with Apple's Apis over any of the pros listed here.

---

And yes, I'm purposely typing API as Api in this thread 😜

[bryankeller]

@teradyl

Is it linkURLs vs linkUrls or is it linkURLS? What do we do with the s?
userIDsToDelete vs userIdsToDelete is another one.

I have never seen anyone make the s capital as well. I don't think this is a real problem. We could always explicitly say what to do in this situation in the style guide, but for the most part I think this one is common sense based on seeing Apple APIs. In fact, I think the proposal makes it way more confusing, because you actually don't have a way to figure out if the s is pluralizing the acronym, or if it's part of the acronym.

userIDsToDelete is crystal clear IMO. userIdsToDelete is the ambiguous one. is Ids IDs or IDS?

[teradyl]

Seems like people are not onboard with this. Closing this until I finish making my PR to change general conventions of Swift guidelines. 😉