TV is an abbreviation for television, why `TVVcr` is good but `TvVcr` is bad?

[yujinlin0224]

Page URL

https://dart.dev/guides/language/effective-dart/style

Page source

https://github.com/dart-lang/site-www/blob/d2d436b3ca51bbd08df4e8f77464aaa8944e297d/src/_guides/language/effective-dart/style.md

Describe the problem

In DO capitalize acronyms and abbreviations longer than two letters like words says

Exception: Two-letter acronyms like IO (input/output) are fully capitalized: IO. On the other hand, two-letter abbreviations like ID (identification) are still capitalized like regular words: Id.

TV is an abbreviation for television, why TVVcr is good but TvVcr is bad?

Expected fix

Change TVVcr to bad and TvVcr to good

Additional context

No response

[danagbemava-nc]

cc: @parlough what are your thoughts on the expected fix?

[parlough]

Thanks for catching this @yujinlin0224, this seems to make sense to me. It seems useful to illustrate this combination of an acronym that is two letters than one that is not, so perhaps we can find a good replacement that fits with the others rather than swapping these.

[yujinlin0224]

I'm not a native English speaker, so I may be wrong, here is my personal opinion:

Rather than using acronyms and abbreviations to distinguish between rules, I prefer to use the source of the letters to distinguish or the pronunciation to distinguish.

1. source of the letters (closer to existing rules and fix TV issue)

   Suppose ab is an acronym or abbreviation of word(s) and xyz is a complete word

   • If the letter of acronym or abbreviation is from the first few letters of the (first if from words) word, use general camel case rule and treat as a single word
     • good: AbXyz, abXyz, XyzAb, xyzAb
     • bad: aBXyz, ABXyz, XyzAB, xyzAB
   • If not from the first few letters of the (first if from words) word, do all capitalize or lowercase it
     • good: ABXyz, abXyz, XyzAB, xyzAB
     • bad: aBXyz, AbXyz, XyzAb, xyzAb

   Real world examples:

   • advertise (abbreviation - ad): use ad or Ad, not AD or aD
   • identification (abbreviation - ID): use id or Id, not ID or iD
   • database (abbreviation - DB): use db or DB, not Db or dB
   • television (abbreviation - TV): use tv or TV, not Tv or tV
   • user interface (acronym - UI): use ui or UI, not Ui or uI

   (Optional) Expend the rule to acronyms and abbreviations that above two letters

   • application (abbreviation - app): use app or App, not aPP or APP
   • cascading style sheet (acronym - CSS): use css or CSS, not cSS or Css
   • Coronavirus disease: use covid or COVID, not cOVID or Covid

2. pronunciation

   • If acronym or abbreviation is read like a word, use general camel case rule and treat as a single word
   • If acronym or abbreviation is read by each letter or its original form, do all capitalize or lowercase it

   Real world examples:

   • advertise (/æd/): use ad or Ad, not AD or aD
   • identification (/ˌaɪˈdiː/): use id or ID, not Id or iD
   • id (/ɪd/): use id or Id, not ID or iD * note that id can also be a complete word in psychoanalysis
   • database: use db or DB, not Db or dB
   • television (/ˌtiːˈviː/): use tv or TV, not Tv or tV
   • user interface: use ui or UI, not Ui or uI

   (Optional) Expend the rule to acronyms and abbreviations that above two letters

   • application (/æp/): use app or App, not aPP or APP
   • cascading style sheet: use css or CSS, not cSS or Css
   • Coronavirus disease: use covid or Covid, not cOVID or COVID

In addition to choosing one of these two rules, if acronym or abbreviation is not in the begin or end of variable, just use general camel case rule and treat as a single word:

• good: XyzAbXyzAbXyz, xyzAbXyzAbXyz
• bad: XyzABXyzAbXyz, XyzAbXyzABXyz, XyzABXyzABXyz

To me it would make more sense to use the pronunciation to differentiate, but it will breaks some words like id which are widely used

[parlough]

Thanks for your detailed thoughts @yujinlin0224!

I'll rope in @munificent as these are his guidelines to see what he thinks.

It sounds like a simple modification to make it more clear would be making the exception be about initialisms (abbreviations that are sounded out by the letter) rather than acronyms.

[munificent]

Honestly... I think the real underlying rule here is just that Id is an exception and all other two-letter acronyms/abbreviations/initialisms are fully capitalized. I don't know why we make an exception for Id. I remember talking about it with other folks at the time that we were first establishing this guideline and most people generally seemed to prefer the d not being capitalized, but I don't know why they prefer that. (Personally, I would be fine either way.)

Maybe we should just write to say that Id is an exception?

[atsansone]

Consider the main documentation style guide: it considers the correct usage to be ID. Also, id is a word on its own. Using ID should improve clarity and consistency. (Sure, I understand it's almost universally accepted to use Id in code, but I think consistency should win out.)

[munificent]

Consider the main documentation style guide: it considers the correct usage to be ID.

That's the guidance for documentation. In doc comments and string literals, yes, you should write it as "ID". Likewise, you should fully capitalize "HTTPS" and "NASA".

But the guidance this issue is talking about is abbreviations appearing in identifiers. That has different capitalization rules from normal English grammar.

[atsansone]

OK, let's back up. The docs as written are correct but unclear. TvVcr works per the rules stated: initial cap acronyms longer than two letters (Vcr: Video Cassette Recorder) and initial cap abbreviations of two or more letters (Tv : Television).

The heading confuses the issue. Perhaps it should be separated into two sections.

DO capitalize acronyms as other identifiers except two letter acronyms in all caps

Capitalized acronyms can be hard to read. Multiple adjacent acronyms can lead to ambiguous names. For example, given a name that starts with HTTPSFTP, there’s no way to tell if it’s referring to HTTPS FTP or HTTP SFTP.

To avoid this, capitalize acronyms longer than two letters as you would any identifier. Set two-letter acronyms in all caps.

DO capitalize abbreviations like other identifiers.

Like acronyms, capitalize abbreviations like regular identifiers.

[munificent]

My understanding is of the terminology is:

• An abbreviation is any shortened form of a word or series of words. So "TV", "DB", "Mr.", "HTTP", and "NASA" are all abbreviations.
• An acronym is an abbreviation formed by taking the first letter of a series of words and where the result is pronounced like a word. So "NASA" is an acronym but "HTTP" is not.
• An initialism is an abbreviation formed by taking the first letter of a series of words and where the result is not pronounced like. So "HTTP" is an initialism but "NASA" is not.

I think that "DB" is more or less an initialism because the term was originally "data base" before becoming fused as "data-base" and then "database" (which is a common process in English). I don't know how to characterise "TV" since "television" has always been a single word and "tele" isn't a meaningful standalone word. It seems like it should be best considered a non-initialism abbreviation. But we wouldn't want it to be "TvVcr" in Dart.

Oh, wait, I've got it now. The linguistic category is a red herring. All we need to care about is whether it is all caps in English. I think the rule can just be:

---

DO capitalize acronyms and abbreviations longer than two letters like words.

Capitalized acronyms can be hard to read, and multiple adjacent acronyms can lead to ambiguous names. For example, given an identifier HTTPSFTP, there's no way to tell if it's referring to HTTPS FTP or HTTP SFTP. To avoid this, most acronyms and abbreviations are capitalized like regular words and this identifier would be HttpsFtp if referring to the former or HttpSftp for the latter.

Two-letter abbreviations and acronyms are the exception. If both letters are capitalized in English, then they should both stay capitalized when used in an identifer. Otherwise, capitalize it like a word.

Examples:

// Longer than two letters, so always like a word:
Http // "hypertext transfer protocol"
Nasa // "national aeronautics and space administration"
Uri // "uniform resource locator"
Esq // "esquire"
Ave // "avenue"

// Two letters, capitalized in English, so capitalized in an identifier:
ID // "identifier", capitalized as "ID"
TV // "television"
DB // "database", originally an acronym from "data base"
IO // "input/output"
UI // "user interface"

// Two letters, not capitalized in English, so like a word in an identifier:
Mr // "mister"
St // "street"
Rd // "road"

When an abbreviation of any form is at the beginning of a lowerCamelCase identifier, it is lowercased:

var httpConnection = connect();
var tvSet = Television();
var mrRogers = 'hello, neighbor';