How should we write the casing of abbreviation in code?

[ThijsTyZ]

Within correct English (some) abbreviations should be written in CAPS, like URL, DOM, ID or API. Using these words, in combination with other words, in code could leads to hard to read code, like JSONAPISDKURL.

If we would consider abbreviations as being normal words, we can apply the same PascalCasing or camelCasing rules to them, so the previous example would be JsonApiSdkUrl in PascalCase and jsonApiSdkUrl in camelCase.

This would also make it easier to have automated switching between different casings, like from PascalCase to camelCase or UPPER_CASE. Or to validate (in linting rule or API's) if the casing is correct.

And another issue with writing abbreviations in CAPS is that the develop needs to know about the context and domain jargon of the project. For example, if your project has some specific abbreviations, like OTA , DNI , VAT, EIN, DUNS and you have to combine them with other abbreviations in a word, you could get really weird words that are impossible to understand if you are not aware of the context, like OTAAPIURL or VATDUNSID or DNIURL or EINAPI.

How should we write the casing of abbreviation in code?

[ThaNarie]

Btw, this mostly applies to initialisms and acronyms, since "normal" abbreviations shouldn't be used most of the times (and are often not even all-caps).

I think it would be most helpful to look at other industry guidelines, see if there is consensus, or if we can just chose our side.

For example, MS says this: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-1.1/141e06ef(v=vs.71)?redirectedfrom=MSDN

• Do not use acronyms that are not generally accepted in the computing field.
• Where appropriate, use well-known acronyms to replace lengthy phrase names. For example, use UI for User Interface and OLAP for On-line Analytical Processing.
• When using acronyms, use Pascal case or camel case for acronyms more than two characters long. For example, use HtmlButton or htmlButton. However, you should capitalize acronyms that consist of only two characters, such as System.IO instead of System.Io.

The last part would fall in line with our "readability" argument.

[skulptur]

I like the guidelines above. How does it work when there is a 2 chararacters abbreviation followed by another word? handleIOValidation or handleIoValidation? Both look bad to me.

[ThijsTyZ]

I don't like the exception for 2 letter words. That means we should also write ID, as in userID.

[ThijsTyZ]

When treating abbreviations as words we can set the naming-convention linting rule to strictCamelCase and StrictPascalCase:

• camelCase - standard camelCase format - no underscores are allowed between characters, and consecutive capitals are allowed (i.e. both myID and myId are valid).
  • strictCamelCase - same as camelCase, but consecutive capitals are not allowed (i.e. myId is valid, but myID is not).
  • PascalCase - same as camelCase, except the first character must be upper-case.
  • StrictPascalCase - same as strictCamelCase, except the first character must be upper-case.

[ThaNarie]

The MS guide is a bit ambiguous, only using 2-letter acronyms for a separate "segment"; System.IO.

id is not an initialisms/acronym, but a generic abbreviation of "identifier". So IMO should be just id and userId, not ID and userID.

[ThaNarie]

I don't mind using the Strict versions for everything, extending the count down to 2 characters.

[ThijsTyZ]

I tried strictCamelCase and StrictPascalCase in an existing project an ran into the following linting errors:

• isIPad
• getIsRTL
• setPastEventsFilterToADate
• setGTMPageData
• fixHeroHeightForIOS
• isRTL

So these values should then be renamed to:

• isIpad
• getIsRtl
• setPastEventsFilterToDate
• setGtmPageData
• fixHeroHeightForIos
• isRtl

I think that is totally fine

[ThaNarie]

LGTM

a and i are the only single-letter-words in English (ignoring things like e-book), and we can do without them in names :)

[skulptur]

@ThijsTyZ much prefer the renamed versions :)

[ThijsTyZ]

To gauge the individual opinions of our team members, please add a 👍 on the option you agree on

[ThijsTyZ]

Option: We should treat abbreviations as words and only capitalize the first character when used in PascalCase or camelCase

Examples: UiElement, UserApi, imageUrl, fixHeroHeightForIos

pros:

• Easy for (automated) switching between different casings, like camelCase, PascalCase and UPPER_CASE
• Improves readability, especially when combining multiple abbreviations in a name, like JsonApiSdkUrl
• We can use more strict linter settings which help to prevent bad code

cons:

• Not 100% correct English
• Does not comply with some excisting TypeScript classes, like HTMLHRElement

[ThijsTyZ]

Option: We should write abbreviations in correct English and write them fully in capitals when used in PascalCase or camelCase.

Examples: UIElement, UserAPI, imageURL, fixHeroHeightForIOS

pros:

• Correct English
• Does comply with existing TypeScript classes, like HTMLHRElement

cons:

• Could lead to hard to read code, like JSONAPISDKURL
• Developer need to be aware of the terminology in the project in order to understand
• Hard for (automated) switching between different casings, like camelCase, PascalCase and UPPER_CASE
• We cannot use strict linter settings for naming convention

[msallent]

The other day on Slack I said I would write it like const htmlHrElement: HTMLHRElement and got weird looks, but if we go with the first option, that’s how it would be written, right?

I personally feel the second option looks cleaner, but if our goal is to enforce consistency all around our projects I think the first option is better, so I’ll vote that one.

[ThaNarie]

No, the first option would be const htmlHrElement: HtmlHrElement - if that would be a type of our own.

If you're using existing types, then indeed, your version is what it would end up with.

[pigeonfresh]

@ThaNarie the type HTMLHRElement is an existing one in this case.

[ThaNarie]

@pigeonfresh That's what I said yes:

If you're using existing types, then indeed, your version is what it would end up with.

[pigeonfresh]

Ah in that case I misread the comment. But I guess you wouldn't create a type that is so similar like an existing one. That confused me. :)

[ThijsTyZ]

Pull Request #35