The great naming debates — still..


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">Some guidelines in the href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/cpconnetframeworkdesignguidelines.asp">Design
Guidelines Document and described in my blog are based on years of
experience with managed code and a deep understanding of how developers think
about problems and how the runtime really works… And other guidelines…well, to
be frank, we flipped a coin.  For
some of the guidelines (mostly casing related) we really could have gone either
way.  What is important about them
is that we use them consistently in the framework. There is inherent value in
conforming.  Developers can predict
how Html or IO will be cased in an API… If you are a long-time managed code
developer I would bet it would look odd to you to see “HTML” or
“Io”. />


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial"> 


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">And then there are the exceptions to
the rule. Nearly every team writing new parts of WinFX has some place they want
to violate these guidelines.  They
have some special reason to want to case their identifiers differently than the
rest of the framework.  Things such
as consistency with an older platform (MFC, HTML, etc), avoiding geo-political
issues (casing of some country names), honoring the dead (abbreviations folks
names that came up with some crypto algorithm), the list goes on and on. style="mso-spacerun: yes">  style="mso-spacerun: yes"> 


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial"> 


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">I am honestly torn in these
cases.  On one had there is only
value in these kind guidelines is everyone one follows them. style="mso-spacerun: yes"> So, we should just force folks to conform
even if it feels a little odd in a particular case. style="mso-spacerun: yes">  On the other hand, I strongly believe
that that the teams building WinFX know their domain best, for most guidelines
they do a great job of making intelligent trade-offs and producing great
APIs.  So should we just leave it up
to the teams to make a call and risk a fairly fragmented world or should push
hard on consistency in these places. 


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial"> 


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">I am really interested in your
opinion of these abstract issues, but I also have a couple of (slightly more
complex) concrete examples for you to weigh in on.


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial"> 


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">ARGB or “From Argument
B”


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">We have the class below in the
framework today.  It successfully
follows the guidelines for casing and uses “Argb” rather than “ARGB”. style="mso-spacerun: yes"> But we have actually gotten bug reports
along the lines “How do you convert a color from an ARGB value, all I see is
methods to convert “from argument b”. 


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">So did we make the right call here?
 Should we continue to use Argb in
future apis (in Avalon for example) or should we use ARGB?


style="FONT-SIZE: 10pt; COLOR: navy; FONT-FAMILY: Arial"> 


style="FONT-SIZE: 8pt; COLOR: blue; FONT-FAMILY: 'Lucida Console'">public struct
style="FONT-SIZE: 8pt; FONT-FAMILY: 'Lucida Console'">System.Drawing.Color
 {


style="FONT-SIZE: 8pt; FONT-FAMILY: 'Lucida Console'"> 


style="FONT-SIZE: 8pt; FONT-FAMILY: 'Lucida Console'">...
   
public static Color FromArgb( style="COLOR: blue">int alpha, Color baseColor);
   
public static Color FromArgb( style="COLOR: blue">int alpha, int red,
int green, int
blue);
    public static
Color FromArgb(int
argb);
    public static
Color FromArgb(int red, style="COLOR: blue">int green, int
blue);
...


style="FONT-SIZE: 8pt; FONT-FAMILY: 'Lucida Console'"> 


style="FONT-SIZE: 8pt; FONT-FAMILY: 'Lucida Console'">} style="FONT-SIZE: 10pt; COLOR: navy; FONT-FAMILY: Arial">


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial"> 


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">ID and Id


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">This is a hard one for me because we
have already messed up the framework… Today the guideline says to use “Id” as an
abbreviation for Identifier and about 75% of the framework follows that
guideline.  The notable exception is
ASP.NET which controls have a commonly used ID tag. style="mso-spacerun: yes"> We closed on the guideline too late to
change ASP.NET, but we are now in the middle of building WinFX, should new APIs
use ID or Id?  For example, Avalon
has the same basic need as ASP.NET and therefore is using “ID” now… Is that
something that is worth fixing? Maybe we need guidelines on when to use “Id” and
when to use “ID”?


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial"> 


style="FONT-SIZE: 10pt; FONT-FAMILY: Arial">Love to hear your
comments!

Comments (48)
  1. Drew Marsh says:

    Well, I’m a big fan of consistency as well. However, as you’ve said there are always exceptions to the rule and in some domains, such as the ARGB example, it makes sense to violate the casing conventions. So, my vote on that specific one is to go all caps. As for ID vs. Id, personally I prefer the latter. It’s an abbreviation of "Identification" which is one word unlike ARGB which is four (Alpha, Red, Green, Blue).

    I think the only way to be consistent is to always raise the flag on any violations and then have specific discussions about each violation. If it truly makes sense within the domain, then it is an exception to the rule and should be let go.

    Just my 2¢,
    Drew

  2. Ken Brubaker says:

    On Pascal cased Acronyms: Stay consistent! I find the few places where you haven’t kept to Pascal casing disconcerting–almost disorienting. "There is great value in great consistency."

    On Argb: I would have to think the solution is to change the acronym. I am sure that ARGB is a standard acronym. However it’s simply confusing, even as all caps. I certainly "Had to go to Docs" to realize it was an RGB + Alpha channel. If you went with AlphaRgb or, simply, Rgba you will probably get a lot more heads nodding.

    On ID: I’m certainly torn when it comes to Id. I’ll have to say that the two letter all caps acronym was one of the hardest pills to swallow in conforming to The Guidelines. Before your RTM release of The Guidelines the standard I set down was all caps on two character acronym identifiers (such as IO) but Pascal casing for two character acronyms *within* an identifier: IoSettings. Instead, you special cased Id. Since you already specified Id across the framework, keep Avalon standard. ASP.NET is all about integrating with an international standard. Avalon is all about forging your own. Still, in another world, I could wish my rule were in effect…

  3. RichB says:

    CLSCompliantAttribute
    Was this an accident?

  4. theCoach says:

    Drew,
    Isn’t ‘Html’ also four words? This is a bit of a special case, though. RGB is a much better known term than, ARGB – should you go back and change the order to RGBA? Wow, that would be painful! I would recommend sticking with the guidelines. From argument B would be ArgB, so a user should figure it out if they are used to consistency – someting they are not now. Let people learn that you are serious about the rules.

  5. Brad Abrams says:

    Yes, CLSCompliantAttribute was a mistake… We closed the naming guideline too late to get this one changed. It should have been ClsCompliantAttribute

  6. Mats Lanner says:

    For what it’s worth, in my opinion ARGB should be all upper case since it’s a domain-specific initialism, it’s also fairly limited in scope in that it’s used for color and that’s it, it’s not really a general purpose concept that shows up all over the place.

    As far as Id goes, I prefer it as Id instead of ID. As Drew pointed out, it’s an abbreviation, so ‘Id’ makes more sense than ‘ID’.

    When it comes to Html vs. HTML, HTML is the most common way to write it outside of code, but given how prevalent it is in use, I think that it would look terrible if it was always written in upper case (e.g. HTMLTextWriter).

    /Mats

  7. Bruce says:

    I think all ID should be changed to Id because we have only one naming guideline. I don’t see any reason to make an exception.

  8. Zhanbo Sun says:

    My blog: http://blogs.gotdotnet.com/ZHANBOS/PermaLink.aspx/16e53e29-7757-4fc6-87e9-db3bd47537fb

    In short, keep WinFx API names consistent. People are getting used to naming guideline.

    We already know why V1.0/1.1 Framework naming is not very consistent (as we closed on the guideline too late). Otherwise, we will be consistent even in V1.0/V1.1. Now we have the clear guideline and people are well aware of it, and we still want to be inconsistent as before?

  9. Ram Hariharan says:

    Personally, I think ID should be allowed. Since ID is an accepted abbreviation often used as a word in English I think it is more intuitive for at least some developers. Further, I fail to see what harm it causes other developers, or the execution quality or security of the code we write.

    I also recognize there are people who have a strong opinion in the opposite direction. Rather than wage a religious war which will result in a binary result, why don’t we just allow both with a preference for one?

    Among the developers I work with, it seems like someone has very skewed priorities when stylistic/aesthetic guidelines are given the same visibility and priority within code checking utilities as the real security and performance issues they find. I find myself puzzled by this utopian totalitarianism …. as if the development world would somehow be happier and more productive if we all used ID versus Id.

    It would be great to have a consistent usage across one companies public namespaces, but I don’t think there’s sufficient consensus in the community to say one is better than another for naturalness of usage.

  10. Dick Dievendorff says:

    It’s a source of typographical errors to have both ID and Id. I’m in the "it’s an abbreviation" camp, so make it Id. It’s even clearer that this should be Id than two-letter acronyms like IO.

    Don’t we also have this problem with DB, as in System.Data.DBConcurrencyException and System.Data.DbType?

  11. Gp says:

    If you are going to make guidelines that define methods of consistency, then I say follow the guidelines. The old dogs will have to learn new tricks, but everyone else who is just learning will always know what is going on. Why would you want to carry-forward poorly enforced conventions into a strongly enforced universe? "Because people will be more familiar, since it is the way we used to do it?" Well, isn’t the whole point of introducing conventions to make everyone do it the SAME way. My personal take is that unless you cannot complete your task without breaking a convention, you shouldn’t break it.

  12. Ryan says:

    Maybe I’m just new-fashioned, but case doesn’t really bother me that much. Most of the time I use Intellisense, or its equivalent in Eclipse.

    Case is one of those (many many) things that developers should just not have to worry about — it should be taken care of by an IDE, either by auto-correction or Intellisense. Bracketing and indenting are two other sensitive "religious" issues that developers waste cycles arguing about.

    If you choose to use an editor without something like Intellisense, then you risk wasting your time. 🙂

    That said, I think trusting your teams to follow the guidelines and deviate where they think is appropriate is best.

  13. ARGB is Alpha, Red, Green, Blue. Notice the commas. That’s differnet than HyperText Markup Language.

    Also, in the namespace naming guidelines, it says to stick with the brand. That should be applied to classes when needed. If the common "brand" name of a class conflicts, the brand should take priority, if it’s important enough. So if it’s common to have RSA in caps, because that’s it’s "brand", no big deal. Also note that RSA is "Rivest, Shamir, Adleman", more commas.

    ID vs Id? ID is "common" and Id is "think different"? If someone has a problem with it, they can use VB and case it as they like. 🙂 I do think that Id is "correct" though.

  14. Sergio Pereira says:

    As you mentioned in your post, the developers of the API know the most about their audience. A general rule is needed but very common terms in the scope of the API should be allowed.
    For a general rule I personally like all caps for 3 chars or less acronyms, and pascal case for the longer ones, but always pascal casing when the term is part of a multi-word member (example: IoException instead of IOException).

  15. Albert says:

    The names of our managed namespaces violate the guidelines because our company name has a very special casing. We won’t change the casing just to adhere to the guidelines. People would find it odd to type the name with any other casing than the one we used for the past 20 years. I think consistency is great but there’ll always be exceptions.
    I’d say if there’s 100% consistency how a name spelled then don’t change it just to comply with the guidelines (brand names, names of crypto folks)
    If there’s inconsistency today (ID, argb etc.) then enforce compliance.

  16. A real example of branding: SqlClient should be SQLClient, since it’s a client for SQL Server, not a client for Structured Query Language. That’d help the framework differentiate between a Microsoft product, and SQL in general.

  17. Mitch Walker says:

    ARGB is an acronym that is widely used and agreed upon in the world outside of .NET, so I think we should be consistent and keep it as is (or rather, I am for ARGB instead of Argb). It is ARGB, not RGBA because that is the byte order that the components appear.

  18. ET says:

    Frankly this is a tempest ina teapot. The REAL convention is that either PascalCasing or camelCasing hould be used.

    ANYTHING else is really an exception and should be justified. The worst is to have some method that has a whole bunch of caps in it and you can’t tell where one word begins and the next one ends.

    By that standard, Argb and Id win out. I personally agree that we have too many acronyms anyway and that AlphaRgb makes more sense. People are adding more and more TLAs all the time, usually with bogus justifications. The API should be approachable.

    Special-casing the two-letter acronyms just opened the door to these kind of (IMHO) silly debates. AT least the rule was simple when it was just two-letter contractions were alowed to be uppercase. Now there’s linguistic debates over whether a word is an acronym or contraction or word?

    Give me a break. Pick a simple rule and enforce it. Forget the "foolish consistency" argument, despite the egregious example of ARGB (due to using an acronym that people really aren’t familiar with, and the Color class is used by people from all domains), no one is really having trouble with casing, people make it up all the freaking time.

    Pick a simple rule and enforce it. As a library writer, don’t make me look in a damn dictionary every time to decide casing. Limit the number of exceptions greatly, you’ve opened the door too far already.

  19. Steven says:

    Casing should be Argb, AlphaRgb or AlphaRedGreenBlue. Full caps as a genral rule will always lead to base cases, Just imagine XAMLLoader (sucks) versus XamlLoader (nicer) or MSBuild (sucks) and so on. Programmers doing ASCII art with names is always bad. Try to avoid acrynoms whenever possible (every acrynom results in at least a dozen people asking what it means). ID is somewhat of an exception and even there IDConverter should be called IdentityConverter.

  20. Tor says:

    One of the nicest features of the framework when it was released was the consistency. There is going to be annoying entropy in the framework in the future, because it is unavoidable. However, with sufficient effort it is possible to keep it under reasonable control for a while. A few wrong decisions at this early stage will surely shorten the time until the framework is just a big mess. Look up the theory of broken windows if you haven’t already.

    Look at C/C++. It’s not really a language, it’s a universe of vastly distinct environments. Win API, COM, MFC, Boost, Linux kernel, to name a few. How many ways to represent a string again?

    From the discussion above, I have not seen a single compelling reason why a name such as FromARGB would be justified. As for ID/Id, well if it’s already broken, it is too late to fix it. You’ll have to allow both, but you still need to consider conventions whenever you introduce another ID/Id. Is it related to the ASP.NET ID tag in any way? Then it’s ID. Otherwise it’s Id.

    Please, don’t let anyone get away with breaking any guidelines without an unthinkably good reason. In my opinion it is not inappropriate to think of your group as the guidelines *police*. Knowing the domain best does not give anybody the right to break naming conventions.

  21. Keith Patrick says:

    I prefer consistency over all else. For ID, I prefer ID over Id because the guidelines say 2 or less is all caps and 3 or more is Pascal. Why would ID be treated differently than IO? They are both spoken as letters.
    On the topic of SqlClient, if it’s branded (SQL Server Client), than I would think it should be called SQLServerClient rather than SqlClient so as not to confuse someone into thinking it is just a SQL client

  22. Pierre Arnaud says:

    What about the event naming in WinForms? I read in the guidelines that a verb should be either used as past tense or continuous (Closed, Closing). Where does the "Click" come from? Consistency would have mandated a Clicked event instead?
    And with respect to RGB, ARGB, etc. I definitely prefer the upper casing. Just as IO.
    And with Unicode, we could consider writing (small Greek letter alpha)RGB 🙂

  23. Darrell says:

    My Steve Ballmer impersonation:
    Consistency, consistency, consistency, consistency, consistency, consistency!!!

    Two letter abbrevs are CAPS, anything else is PascalCased (current rule), but I would rather break it down to Pascal case everything. (i.e., System.Io) 1 simple rule, baby, and you can transfer your knowledge across the framework… which becomes increasingly important the bigger that it gets!

  24. dannyR says:

    Ditto what others have said: FromArgb and consistency. But then again, I loved hungarian (proper Simonyi hungarian–not the fake hungarian a lot of MS developers used). If you understand naming conventions, and conventions are followed, you should be able to infer Argb is an atom. You may not know what the heck it is, but you’ll know it is a thing. Also, the guidelines should say that the article "a" is never used in names. You would never, for example, name a function BakeAJellyDonut. You would name it BakeJellyDonut. It’s unfortunate that someone prepended an "a" onto an existing, well-known acronym (rgb). That invites confusion (another guidelines hint?). But good code readers should at least know that there is something called an argb.

    ID? Well, you already yellowed the pool. Leave it alone.

  25. Shane King says:

    Yeah I have to agree, special casing the 2 letter ones was a silly mistake, and if possible should be changed before even more damage is done.

    As a general note, the less caps the better. Caps are hard to type.

  26. LeonBambrick says:

    ‘well, to be frank, we flipped a coin’

    i like your honesty here.
    for most conventions, it is whatever works best that matters.
    for others, it’s just consistency. in such a case, a partially fascist model is needed where certain people can proscribe the convention, and the rest can have the good sense to obey.

    Do you think it’s reasonable to continue using Hungarian notation on projects where external API’s are not published? For example, do you think that for purely in-house projects, the use of Hungarian might be still quite valid?

    Or is it set to go the way of the dodo, even for internal projects?

  27. Alexander Kogtenkov says:

    The guidelines make our life easier. If they are followed, the identifiers become evident. People get accustomed to the style and can derive the semantics from the name alone. Any occurrence of a "non-standard" (or "exceptional") style raises a flag that the name denotes something special or non-expected.

    Using different naming schemes in the product(s) of the same company gives a feeling that
    1) nobody cares about the API and does whatever (s)he wants
    2) the company hires detached developers that do not know about each other activities/results
    3) the API is short-term and will be changed soon
    4) the API is not thoroughly designed and/or is not carefully implemented

    I would use "Id" and change "Argb" to "AlphaRgb", "Rgba" or some similar non-confusing name.

  28. Michael says:

    Another vote for consistency (though ID is ok with me).

  29. Alex says:

    Please rename the System.STAThreadAttribute in the future release of framework. I’m for consistency too.

  30. Steve Dunn says:

    Just a small comment regarding the ARGB Argb issue. Those that are taking Argb as ‘Argument B’ are not following another guideline of using English method and argument names. The correct declaration according to this guideline would be "public static Color FromArgumentB(int alpha, Color baseColor);"

    Regarding the ID issue, I prefered Id. I’m sure that’s gonna change the world! 🙂

  31. Anonymous says:

    Is this a replacement for ASP.NET or a replacement for WinForms, or both? If it isn’t both, go with whichever matches. If both… hey, is it too late to get typedefs?

  32. Frank Hileman says:

    Whenever I tried to capitalize the last letter of something like ARGB, or an abbreviation, it became difficult to visually distinguish that term from the next one in the identifier, because the only visual break comes from the capitalization. So I don’t see how you could consider any other method; go for consistency. It was a good choice.

  33. Gerry Shaw says:

    A new platform comes about every 10 years. C 30 years ago, C++ 20 years ago, Java 10 years ago, .NET now. The platform is going to live for 20+ years, get it right. Not many people get a chance to design a new platform that is going to be used as widely as .NET. Consistency is the most important thing you can do early in the development (which .NET still is). I vote PlatformId, VertexArgb.

  34. Keith Hill says:

    +1 for Argb. Make a rule and stick with it. If you start to deviate then you wind up with stuff like SQLClient or PutARGBInCMYK (is that "put arg bin cmyk"?). I’ve had a similar debate about SI prefix names e.g. is it Si.milli or Si.Milli?

    +1 for Id. Same as above.

  35. Mitch Denny says:

    Hi Brad. I’d go for ID over Id, even though its not an acronym it is often viewed in that light, and it’d just be a pain to have XAML files with Id and ASP.NET files with ID. Imagine the confusion when you start generating XAML files dynamically with ASP.NET!!!

    I actually don’t mind Argb.

  36. Roy says:

    Shouldn’t that be "Xaml" and not "XAML"? <g>.

  37. Aaron says:

    I seem to be in the minority but I agree with two letters is caps, 3 or more is pascal. I can’t stand seeing ID written Id. When I see a function like "GetId" I think "get id? Does this function call Carmack about DOOM? Or is it something about Freud?" When I see "GetID" I instantly think "I-D. identity". So I guess I’d have to be taught new tricks. 🙂

  38. Great comments. Love the issue. As for ID vs Id for our property on Element…there is still some thinking to do.
    I list the current state here: http://longhornblogs.com/rrelyea/posts/1632.aspx

  39. X says:

    Personally, I like ARGB. First, it’s what I’m used to (though Intellisense helps out here). Plus, it’s an acronym – so surely each letter of it should be upper case? Having it in capitals makes it easier to work out what it means (Argb = Arg B? Alpha Red Green Blue?)

    Similarly, for ID vs Id, I prefer ID. If I were to see "ID" in some code, I’d know it was an identifier tag. If I saw "Id", I might be tempted to look for "Ego" and "SuperEgo" tags as well…

    Ultimately though, IMHO it really doesn’t matter that much…

  40. James Bellinger says:

    I prefer the current set-up where a one or two letter acronym is upper-case and one with three or more letters is Pascal-cased. It just seems cleaner. ID makes more sense based on that rule, and also because it’s the ordinary way of writing it in English. The 1.1 Framework was less consistent than the 1.0 Framework, and even the 1.0 Framework had some abominably done classes.. :/

  41. Ken Brubaker says:

    For my own reference, I thought I’d compile a quick list of design guidelines added by Brad Abrams, et al.

  42. Mike Portsmouth says:

    I’m, a bit confuesed with Argb vs ARGB, surely if, as at the very top it states ‘From Argument B’ it should be ArgB and none of the above if it is from Argument B, and ARGB if it pertains to AlphaRedGreenBlue? …

  43. Henry Stapp says:

    I’d vote for consistency. Every exception you add requires mental storage for developers to remember, and makes the Framework as a whole more difficult to use. Go for "Id" not "ID".

  44. Brad Abrams says:

Comments are closed.

Skip to main content