Naming style for abbreviations in type/function names

[Peter Kasting]

This question came up in a recent codereview.  +CCing a few people who generally have style opinions.

What should we do about capitalization of abbreviations such as "UI" in type and function names, for example "GetUIThread()"?

Here's the most applicable section of the Google style guide: "Type names start with a capital letter and have a capital letter for each new word" ( http://google-styleguide.googlecode.com/svn/trunk/cppguide.html#Type_Names ).

The question is, are all abbreviations words?  Are only acronyms words?  And whatever we choose, how important is this rule versus consistency with existing code?

The style guide examples here are a bit unclear, because they only give a sample for the abbreviation "URL", which many people pronounce as a word (thus making it an acronym).

Chromium style is inconsistent.  When it comes to URL, the numbers are about 4:1 in favor of "URL" over "Url":

https://code.google.com/p/chromium/codesearch#search/&q=URL%20case:yes%20-file:v8%20-file:third_party%20-file:usr/%20file:%5C.(h%7Ccc)&sq=package:chromium&type=cs

https://code.google.com/p/chromium/codesearch#search/&q=Url%20case:yes%20-file:v8%20-file:third_party%20-file:usr/%20file:%5C.(h%7Ccc)&sq=package:chromium&type=cs

However, when it comes to something like "UI", the spelling "Ui" is extraordinarily uncommon, with ~150 instances in the whole codebase.  I couldn't put together a good regex to exclude false positives for "UI", but it looks as if there are many thousand of those, so the ratio is probably more like 20:1 or higher:

https://code.google.com/p/chromium/codesearch#search/&q=Ui%5B%5Ea-z%5D%20case:yes%20-file:v8%20-file:third_party%20-file:usr/%20file:%5C.(h%7Ccc)&sq=package:chromium&type=cs

One position is that the style guide here is not sufficiently clear about non-acronym (and thus non-"word") abbreviations for us to enforce such a spelling in cases where the surrounding code consistently capitalizes every letter of the abbreviation.  For abbreviations or code where there is no consistent pattern, do what you like, but if there is a pattern, then match the surrounding code.  (This is also in keeping with the style guide's "be consistent" maxim.)

Another position is that abbreviations are always words, and thus our existing spelling of "UI" is globally wrong; we therefore need to decide whether to change it globally or just use "Ui" in new code (presumably the latter).

PK

[Mark Mentovai]

This comes up on c-style periodically. The style guide was updated (in the past year, I think) to prefer StartRpc(). I don’t like this guidance, I prefer URL and UI in names, but maybe the reason we have style guides in the first place is to keep people like us from painting bikesheds all day long.

http://google.github.io/styleguide/cppguide.html#Function_Names

(Peter, your style guide link is outdated, but you’re forgiven because the redirect from codesite isn’t very effective.)

[Michael Giuffrida]

I don't think it's useful to stress over what is and is not a word. The reason we capitalize is to make terms easier to read, because we can't use spaces (and don't like underscores for some things).

A consistent rule that makes sense to me is that capitalization of terms should only upcase letters, not downcase them. This seems to work without worrying about what's considered an acronym vs. an abbreviation vs. a word:

"get UI thread" becomes GetUIThread, not GetUiThread

"fetch URL" becomes FetchURL, not FetchUrl

"set addr." becomes SetAddr, not SetADDR

"enable Wi-Fi" becomes EnableWiFi, not EnableWifi

-Michael

--
--
Chromium Developers mailing list: chromi...@chromium.org
View archives, change email options, or unsubscribe:
http://groups.google.com/a/chromium.org/group/chromium-dev

[Peter Kasting]

On Tue, Oct 27, 2015 at 4:07 PM, Mark Mentovai <ma...@chromium.org> wrote:

This comes up on c-style periodically. The style guide was updated (in the past year, I think) to prefer StartRpc(). I don’t like this guidance, I prefer URL and UI in names, but maybe the reason we have style guides in the first place is to keep people like us from painting bikesheds all day long.

http://google.github.io/styleguide/cppguide.html#Function_Names

(Peter, your style guide link is outdated, but you’re forgiven because the redirect from codesite isn’t very effective.)

I didn't realize there was a new location for the up-to-date guide, thanks!

That text definitely clarifies things, even though they use "acronym" there where I think they mean any abbreviation (since "RPC" is an initialism).  Like you and Michael, I would prefer the rule some other way, but if the guide is going to be explicit about this I'll obey it.

So, given that the rule is "Prefer to capitalize as words", what shall we do in our codebase?

(1) Globally convert things to this naming style

(2) Don't change existing code just to change it, but if touching it anyway, and in any new code, use this style

(3) Ignore the style rule for some set of things (abbreviations where we're pretty consistent about being the other way?)

I would imagine people would prefer (2), as (1) is a lot of churn, and (3) feels like we're not obeying the style guide.

PK

[Evan Stade]

Your intuition is correct. My vote is for (2). 

[Elliott Sprehn]

I much prefer the google3 style where all acronyms are written just like words, so it's XmlHttpRequest not XMLHTTPRequest, and it's GetUiThread() not GetUIThread(). This makes naming things easier, you just use one consistent rule, and it means you never end up with long strings of all caps in names like XMLDOMRPCHandle.

[Nico Weber]

On Tue, Oct 27, 2015 at 4:07 PM, Mark Mentovai <ma...@chromium.org> wrote:

This comes up on c-style periodically. The style guide was updated (in the past year, I think) to prefer StartRpc(). I don’t like this guidance, I prefer URL and UI in names, but maybe the reason we have style guides in the first place is to keep people like us from painting bikesheds all day long.

http://google.github.io/styleguide/cppguide.html#Function_Names

This guidance makes sense to me. I always mention the Objective-C class NSHTTPURLResponse as a good example why capitalized abbreviations are a bad idea – NSHttpUrlResponse is much easier to read.

It'd be nice if this was consistent in our codebase, but it already isn't, and it probably won't be any time soon, so I'm not sure if worrying about this much is a good use of time. I'd say be consistent in a single identifier (so XMLHttpRequest would be bad, for example), else do what you think makes the most sense in your CL. When reviewing code, be happy with whatever the author did.

[Dana Jansens]

Many acronyms are read as words. Like NASA is read "nah-sah" not "N. A. S. A." I think that's probably related to making them lowercase like words.

UI is different, you say that by saying each letter. Writting that as Ui would suggest you are saying something completely different. It's weird. :/

And there will always be some weird exception or different case. For example GraphicsContext3d? Or GraphicsContext3D? Here you say the D letter as a letter of its own again.

But whatever it is, being inconsistent with the same word (2) is probably the worst possible outcome of this thread IMO.

[Peter Kasting]

On Tue, Oct 27, 2015 at 4:22 PM, Dana Jansens <dan...@chromium.org> wrote:

Many acronyms are read as words. Like NASA is read "nah-sah" not "N. A. S. A." I think that's probably related to making them lowercase like words.

UI is different, you say that by saying each letter. Writting that as Ui would suggest you are saying something completely different. It's weird. :/

Yes, this distinction is what I was trying to highlight by using "acronym" ("pronounced as a word") distinctly from the superset "abbreviation" (also covers initialisms).

But whatever it is, being inconsistent with the same word (2) is probably the worst possible outcome of this thread IMO.

Does that mean you're suggesting we do (3) then?

PK

[Dana Jansens]

Yes, I agree with everything Nico said.

[Peter Kasting]

Ah, I didn't perceive Nico as voting for (3), but rather voting for "don't bother about enforcing this rule or the lack thereof".  (Which is an outcome I'm probably pathologically unable to personally implement.)

PK

[Evan Stade]

On Tue, Oct 27, 2015 at 4:22 PM, Dana Jansens <dan...@chromium.org> wrote:

On Tue, Oct 27, 2015 at 4:16 PM, 'Peter Kasting' via Chromium-dev <chromi...@chromium.org> wrote:

On Tue, Oct 27, 2015 at 4:07 PM, Mark Mentovai <ma...@chromium.org> wrote:

This comes up on c-style periodically. The style guide was updated (in the past year, I think) to prefer StartRpc(). I don’t like this guidance, I prefer URL and UI in names, but maybe the reason we have style guides in the first place is to keep people like us from painting bikesheds all day long.

http://google.github.io/styleguide/cppguide.html#Function_Names

(Peter, your style guide link is outdated, but you’re forgiven because the redirect from codesite isn’t very effective.)

I didn't realize there was a new location for the up-to-date guide, thanks!

That text definitely clarifies things, even though they use "acronym" there where I think they mean any abbreviation (since "RPC" is an initialism).  Like you and Michael, I would prefer the rule some other way, but if the guide is going to be explicit about this I'll obey it.

So, given that the rule is "Prefer to capitalize as words", what shall we do in our codebase?

(1) Globally convert things to this naming style

(2) Don't change existing code just to change it, but if touching it anyway, and in any new code, use this style

(3) Ignore the style rule for some set of things (abbreviations where we're pretty consistent about being the other way?)

I would imagine people would prefer (2), as (1) is a lot of churn, and (3) feels like we're not obeying the style guide.

Many acronyms are read as words. Like NASA is read "nah-sah" not "N. A. S. A." I think that's probably related to making them lowercase like words.

UI is different, you say that by saying each letter. Writting that as Ui would suggest you are saying something completely different. It's weird. :/

At the risk of bike shedding, how does this explain the style guide's example of StartRpc?

 

And there will always be some weird exception or different case. For example GraphicsContext3d? Or GraphicsContext3D? Here you say the D letter as a letter of its own again.

But whatever it is, being inconsistent with the same word (2) is probably the worst possible outcome of this thread IMO.

Technically this inconsistency already exists, and this thread is largely about which direction to move in to correct the inconsistency.

[Dana Jansens]

I guess I read them as similar. Prefer using ThisStyle cuz it's nicer usually. Some places people will hate it (eg Ui bothers me :P), and it's not worth arguing about. :)

Maybe I additionally think consistency with a single meaning of an acronym is especially important. It makes things like greping far more valuable than if it changes from place to place.

[Peter Kasting]

Based on feedback, I propose this:

* The style guide says to capitalize abbreviations like words, so do that.

* This isn't important enough to go change existing code just to comply with this.

* It also isn't so important that if an author and a reviewer are in agreement that doing something else is fine, and consistent with surrounding code, they have to change course.

* But, if there's any disagreement or uncertainty, or people don't feel strongly about anything in particular, abide by the first rule.

Unless this isn't acceptable, I'll aim to abide by this going forward.

PK

[Thiago Farina]

On Tue, Oct 27, 2015 at 9:43 PM, Dana Jansens <dan...@chromium.org> wrote:

On Tue, Oct 27, 2015 at 4:36 PM, Peter Kasting <pkas...@google.com> wrote:

On Tue, Oct 27, 2015 at 4:33 PM, Dana Jansens <dan...@chromium.org> wrote:

On Tue, Oct 27, 2015 at 4:24 PM, Peter Kasting <pkas...@google.com> wrote:

On Tue, Oct 27, 2015 at 4:22 PM, Dana Jansens <dan...@chromium.org> wrote:

Many acronyms are read as words. Like NASA is read "nah-sah" not "N. A. S. A." I think that's probably related to making them lowercase like words.

UI is different, you say that by saying each letter. Writting that as Ui would suggest you are saying something completely different. It's weird. :/

Yes, this distinction is what I was trying to highlight by using "acronym" ("pronounced as a word") distinctly from the superset "abbreviation" (also covers initialisms).

But whatever it is, being inconsistent with the same word (2) is probably the worst possible outcome of this thread IMO.

Does that mean you're suggesting we do (3) then?

Yes, I agree with everything Nico said.

Ah, I didn't perceive Nico as voting for (3), but rather voting for "don't bother about enforcing this rule or the lack thereof".  (Which is an outcome I'm probably pathologically unable to personally implement.)

I guess I read them as similar. Prefer using ThisStyle cuz it's nicer usually. Some places people will hate it (eg Ui bothers me :P), and it's not worth arguing about. :)

Ui really strikes me too! UI reads much better imo, as it is an abbreviation for User Interface. I even saw a change that introduced a class with Ui and asked the author to change to UI. As much as I prefer URL rather than Url as it stands for Uniform Resource Locator. Url sounds it is a word, when it isn't.

I think these could be left to the judgement of reviewers.

--

Thiago Farina

[Matt Menke]

On Tuesday, October 27, 2015 at 7:21:15 PM UTC-4, Nico Weber wrote:

On Tue, Oct 27, 2015 at 4:07 PM, Mark Mentovai <ma...@chromium.org> wrote:

This comes up on c-style periodically. The style guide was updated (in the past year, I think) to prefer StartRpc(). I don’t like this guidance, I prefer URL and UI in names, but maybe the reason we have style guides in the first place is to keep people like us from painting bikesheds all day long.

http://google.github.io/styleguide/cppguide.html#Function_Names

This guidance makes sense to me. I always mention the Objective-C class NSHTTPURLResponse as a good example why capitalized abbreviations are a bad idea – NSHttpUrlResponse is much easier to read.

So why is the "S" capitalized there?

[Avi Drissman]

Objective-C has no namespacing, so the style is to use two capital letters at the beginning of class names to do pseudo-namespacing.

That's not a Google style guide thing, but an Objective-C convention from the mists of time. ref ref

Avi 

[Mark Mentovai]

Dana Jansens wrote:

Many acronyms are read as words. Like NASA is read "nah-sah" not "N. A. S. A." I think that's probably related to making them lowercase like words.

UI is different, you say that by saying each letter. Writting that as Ui would suggest you are saying something completely different. It's weird. :/

That’s a dangerous rule to adopt. We use URLs all over Chrome, for example. As everyone knows, URL is an initialism correctly pronounced “You Are Elle,” but that doesn’t stop people from speaking it as if it’s a male given name.

[Stuart Morgan]

On Tue, Oct 27, 2015 at 5:04 PM Thiago Farina <tfa...@chromium.org> wrote:

I think these could be left to the judgement of reviewers.

Lots of people disagree with some specific rule in the style guide and think that rule should be up to individual judgement (so that they can choose not to follow it). The premise of having a style guide is that we don't do that, and instead we all follow the guide. The "Rpc" example in the guide makes the intent clear, even if the word choice is confusing.

I definitely think we should do 2 (or at least the slightly weaker version of 2 that Peter proposed). Option 3 pretty much guarantees a series of arguments in the future about exactly which things should be exempted, and would make the style guide harder to learn since everyone would need to learn the list of exceptions. (And since people would forget what the exceptions are sometimes, the codebase would probably not become much more consistent over time.)

-Stuart

P.S. As a fun side-note, because the ObjC style guide generally follows Apple's conventions, iOS code actually uses different capitalization for abbreviations depending on the language of that piece of code (just as with variable names). So if you see HTTP or URL in ObjC Chromium code, don't be surprised; that's actually correct.

[Thiago Farina]

On Wed, Oct 28, 2015 at 12:21 PM, Stuart Morgan <stuart...@chromium.org> wrote:

On Tue, Oct 27, 2015 at 5:04 PM Thiago Farina <tfa...@chromium.org> wrote:

I think these could be left to the judgement of reviewers.

Lots of people disagree with some specific rule in the style guide and think that rule should be up to individual judgement (so that they can choose not to follow it). The premise of having a style guide is that we don't do that, and instead we all follow the guide. The "Rpc" example in the guide makes the intent clear, even if the word choice is confusing.

I definitely think we should do 2 (or at least the slightly weaker version of 2 that Peter proposed). Option 3 pretty much guarantees a series of arguments in the future about exactly which things should be exempted, and would make the style guide harder to learn since everyone would need to learn the list of exceptions. (And since people would forget what the exceptions are sometimes, the codebase would probably not become much more consistent over time.)

I think it will just become more inconsistent over the time (silos are formed by different teams). People will let both forms of Url/URL go in for sure. Not every reviewer will or remember to enfore 'Url' over 'URL' for example.

People are already allowing fooBar (instead of foo_bar) in C++ code, what more can we say :)

--

Thiago Farina

[Stuart Morgan]

On Wed, Oct 28, 2015 at 9:18 AM Thiago Farina <tfa...@chromium.org> wrote:

I think it will just become more inconsistent over the time (silos are formed by different teams). People will let both forms of Url/URL go in for sure.

It cannot possibly be the case that codifying an exception in the Chromium style guide to leave it to each person's judgement would make that *less* true that making the official guidance be 'follow the style guide when adding/changing code'.

Style guides make style silos less likely, not more.

 

Not every reviewer will or remember to enfore 'Url' over 'URL' for example.

This is true of everything in the style guide. Given that, it seems like you are really arguing that we shouldn't bother having a style guide, which is not in scope here. Trying to turn this into a philosophical argument about the value of having a style guide is not productive.

Chromium follows a style guide, and the style guide has an explicit rule about this case. For us to codify a project-level exception we need a good argument that Chromium has a specific reason that it makes sense to be different. Neither "people might forget" nor "some people personally don't like it" are Chromium-specific arguments.

 

People are already allowing fooBar (instead of foo_bar) in C++ code, what more can we say :)

We can say that it's a clear violation of the style guide, and point it out when we notice it, just like any other style violation.

-Stuart

[Thiago Farina]

On Tue, Oct 27, 2015 at 8:50 PM, 'Peter Kasting' via Chromium-dev <chromi...@chromium.org> wrote:

Another position is that abbreviations are always words, and thus our existing spelling of "UI" is globally wrong; we therefore need to decide whether to change it globally or just use "Ui" in new code (presumably the latter).

Peter, are you in favor of using 'Ui' in new code? The style guide says 'Use common sense and BE CONSISTENT.' . My understand from that is if we already have classes being named with UI, new code would be named using 'UI' too. Why deviate?

[1] - http://google-styleguide.googlecode.com/svn/trunk/cppguide.html

-- 

Thiago Farina

[Mark Mentovai]

Thiago Farina wrote:

I think it will just become more inconsistent over the time (silos are formed by different teams). People will let both forms of Url/URL go in for sure. Not every reviewer will or remember to enfore 'Url' over 'URL' for example.

I’m fairly particular about style, but this isn’t really something I’m very concerned about. Our style guide didn’t express a preference between URL and Url until fairly recently, and I think that this is the first time that it’s coming up on chromium-dev. If the codebase were already uniform in this regard, I think it’d be a different matter, but for the time being, if someone accidentally slips a new URL past the goalie, I can’t see how it’d be a great loss to readability or any subteam or individual.

(Given my personal preference, I might even secretly be glad that a new URL had survived review, but I don’t think that’s coloring my judgment here.)

[Peter Kasting]

On Wed, Oct 28, 2015 at 10:31 AM, Thiago Farina <tfa...@chromium.org> wrote:

On Tue, Oct 27, 2015 at 8:50 PM, 'Peter Kasting' via Chromium-dev <chromi...@chromium.org> wrote:

Another position is that abbreviations are always words, and thus our existing spelling of "UI" is globally wrong; we therefore need to decide whether to change it globally or just use "Ui" in new code (presumably the latter).

Peter, are you in favor of using 'Ui' in new code? The style guide says 'Use common sense and BE CONSISTENT.' . My understand from that is if we already have classes being named with UI, new code would be named using 'UI' too. Why deviate?

All this has been discussed already and you're not raising any new arguments.  Use "Ui" and not "UI" in new or modified code.  End of story.

PK 

[Michael Giuffrida]

Is this the same story for JavaScript? Web APIs seem to mostly use uppercase, e.g. "HTMLElement" or "encodeURIComponent".

BTW, this actually can be awkward in our extensions API, or in generated code in general. Suppose an extension IDL defines a type using uppercase URL:

dictionary Results {

    DOMString someURLScheme;

    DOMString[] dataURLs;

}

The generated C++ extensions code will define the Results class with these members:

  std::string some_url_scheme;  // Fine.

  std::vector<std::string> data_ur_ls;  // Crap.

--

[Elliott Sprehn]

On Thu, Oct 29, 2015 at 8:10 PM, Michael Giuffrida <mich...@chromium.org> wrote:

Is this the same story for JavaScript? Web APIs seem to mostly use uppercase, e.g. "HTMLElement" or "encodeURIComponent".

BTW, this actually can be awkward in our extensions API, or in generated code in general. Suppose an extension IDL defines a type using uppercase URL:

dictionary Results {

    DOMString someURLScheme;

    DOMString[] dataURLs;

}

The generated C++ extensions code will define the Results class with these members:

  std::string some_url_scheme;  // Fine.

  std::vector<std::string> data_ur_ls;  // Crap.

 

Blink's idl compiler allows annotations to handle cases like this, so you'd do ImplementedAs=data_urls or whatever was needed.

It's a separate issue, but we should really figure out how to harmonize the various bindings generators. Having one in blink and one for extensions, and the non-idl based gin ones adds a lot of complexity.

- E

[John Abd-El-Malek]

Apologies for coming late to this.

I think we should stick to the style guide for new abbreviations. But many instances of UI etc already exist. I don't think anyone is advocating doing a mass rename (which I also think we shouldn't do). In that case, consistency is one of the goals of the style guide, and I think we should ensure we don't use two different capitalizations for abbreviations in the codebase.

From the style guide:

Be consistent with existing code

Using one style consistently through our codebase lets us focus on other (more important) issues. Consistency also allows for automation: tools that format your code or adjust your #includes only work properly when your code is consistent with the expectations of the tooling. In many cases, rules that are attributed to "Be Consistent" boil down to "Just pick one and stop worrying about it"; the potential value of allowing flexibility on these points is outweighed by the cost of having people argue over them.

--