Site-www: Clarify why Id is capitalized that way

[kwalrath]

People keep thinking we've made a mistake, so I think we need to make the explanation harder to miss.

Related: #2455, #2392, #2053

[aizatazhar]

I feel that confusion arises because of not knowing the subtle difference between abbreviations and acronyms so describing the abbreviation/acronym might be helpful. Additionally, how about creating a new line with bolded "Exception:" which is consistent with the rest of the document? Here's what I propose:

---

To avoid this, acronyms and abbreviations are capitalized like regular words.

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.)

---

What do you think @kwalrath?

[kwalrath]

I like your idea, but I tweaked it slightly to add examples and change the capitalization of the definition. What do you think?

One thing that slightly bothers me is that I think of "IO" as an initialism, not an acronym. But I suppose "IO" might be both.

[kwalrath]

In that same example, I don't understand why it's ui but IO. @munificent?

[munificent]

In that same example, I don't understand why it's ui but IO.

The intent was to show how leading abbreviations are handled lowerCamelCase identifiers. Maybe we should be clearer by showing the context where the examples are used so that the mandated capitalization is clearer:

// Good:
class HttpConnection {}
class DBIOPort {}
class TVVcr {}
class MrRogers {}

var httpRequest = ...
var uiHandler = ...
Id id;

// Bad:
class HTTPConnection {}
class DbIoPort {}
class TvVcr {}
class MRRogers {}

var HttpRequest = ...
var UiHandler = ...
ID iD;

?

[aizatazhar]

Yup! The tweaks and context in the examples definitely made it a lot clearer.

For the bad examples var HttpRequest = ... and var UiHandler = ..., would a better bad example be var hTTPRequest = ... and var uIHandler = ..., since they are variables so lowerCamelCase is expected, but the section is telling us to treat acronyms and abbreviations as regular words instead of fully capitalizing?

[munificent]

For the bad examples var HttpRequest = ... and var UiHandler = ..., would a better bad example be var hTTPRequest = ... and var uIHandler = ...,

"Better bad". :) Yes, I think those help clarify what we're trying to say.

[aizatazhar]

"Better bad". :)

Haha I noticed that and was contemplating saying "badder" :')

Is it alright if I made a PR for this issue?

[kwalrath]

Is it alright if I made a PR for this issue?

A PR would be great. Thanks!

[aizatazhar]

Thanks so much for the help @kwalrath @munificent :D