Framework Design Guidelines: Capitalization Rules for Identifiers


Continuing in the series of discussing topics from the Framework Design Guidelines


 


Expert from 3.1.1 Capitalization Rules for Identifiers


 


There are two appropriate ways to


capitalize identifiers, depending on the use of the identifier:


PascalCasing


camelCasing


The PascalCasing convention, used for all identifiers except parameter


names, capitalizes the first character of each word (including acronyms


over two letters in length) as in the following examples:


 


BRAD ABRAMS In the initial design of the Framework we had hundreds


of hours of debate about naming style. To facilitate these debates we


coined a number of terms. With Anders Hejlsberg, the original designer of


Turbo Pascal, and a key member of the design team, it is no wonder that we


chose the term PascalCasing for the casing style popularized by the Pascal


programming language. We were somewhat cute in using the term camel-


Casing for the casing style that looks something like the hump on a camel.


We used the term SCREAMING_CAPS to indicate an all-uppercase style.


Luckily this style (and name) did not survive in the final guideline.


 


OK – tell me the truth… who misses SCREAMING_CAPS in public APIs?

Comments (15)

  1. Jonathan says:

    Miss? Too strong a word, more like fondly recollect how easy it was to tell you were working with a constant.

    Have you noticed your Archives show you’ve posted 4 times in November 2005?

  2. Every single person with whom I work and has worked before with COM, etc., despite my constant requests.

    They even got to put it (as a majority decision) in the coding standards. Now I have to deal with SCREAMING_CAPS constants and readonly fields. Ecch.

  3. Ron Krauter says:

    Brad,

    So, how are we supposed to name constants in our applications?

    Are you saying this is wrong?

    public const string SERVER_DOWN = "The server is not responding";

    Thanks,

    -ron

  4. Why on earth do you need SERVER_DOWN constant?

    It hurt the eyes to read it, it is certainly not more readable.

    What about:

    public const string ServerDown = "The Server is not responding";

    If this so bad?

    return Errors.ServerDown;

    vs.

    return Errors.SERVER_DOWN;

    What is easier to read?

  5. Shital Shah says:

    One specific instance where this naming guidelines is inconvinient is when you have to name a parameter and you already have a property with the same name. This is often re-occuring situation. For instance, what would you name the parameter in CheckAddress method below?

    string Address

    {

    get {…}

    set {…}

    }

    bool CheckAddress(string address)

    {



    }

    Certainly naming as ‘address’ makes sense but it conflicts with property name just by a case. I encounter this scenarios very often in different designs and it gets worse in VB. I’ve seen people renaming the parameter as addr (yes!), addressToUse, addressToValidate, paramAddress and so on. In some companies I even see a policy to prefix every parameter by the word ‘param’ to avoid such collisions and inconsistancies.

    What’s your take?

  6. Ugh! If I would’ve seen SCREAMING_CAPS in the public .NET framework APIs, I would’ve left for J2EE. :-p

    I despise SCREAMING_CAPS. :X

  7. Keith Patrick says:

    Shital: the case difference is perfectly acceptable; I find it easier to remember that my params that correspond to properties differ only in name, so it’s easier to remember (part of the purpose of the guidelines is to reduce the # of words used to describe things, and sharing param names with props helps this).

    To really mess with you, Java makes it even more confusing with camel casing of member fields, and I seem to recall in the spec, it even said that this is preferred:

    private Object address;

    public void setAddress(Object address) {

    this.address = address;

    }

    so basically, instead of case differentiating, you are required to get in the habit of using the this pointer for members (but I use "this" as a rule anyway)

  8. michkap says:

    Speaking personally, I have never minded screaming caps as they are called here in any of the places where they are seen in the Win32 API (mainly constants and types), as they provided easier differentiation of various identifiers.

    Sometimes we try so hard to be different that we forget about some of the benefits of how things are done….

  9. Chris Hedgate says:

    >The PascalCasing convention, used for all identifiers except parameter names, capitalizes the first character of each word (including acronyms over two letters in length)…

    Regarding two-letter identifiers:

    I can still not understand why two-letter identifiers should be treated differently than other identifiers, or other two-letter words for that sake. The supposed reason is that it is more readable, but I do not agree with that. Consider the following example:

    public void InsertIOInMiddle(…)

    Why is IO all caps and Is in PascalCasing? Why not simply use InsertIoInMiddle? As Brad himself saidin his PDC pre-con, every exception to the guidelines makes it easier to make mistakes. The guideline is acronyms are PascalCased, so why make an exception for two-letter acronyms?

  10. SN says:

    Google test for acronyms: I had to write a function that took any object and returned the OLE automation date. I called the method ToOADate following the DateTime type’s To/FromOADate methods. The code analysis tool in VS 2005 does not like it.

    To me coming up with guidelines is the easy part, enforcing them is the tricky thing. What are you guys doing about enforcing? Internally in MS do you make devs use the code analysis tool?

    I am guess it is close to being impossible to go back and change all the .NET BCL names to follow the guidelines. But going forward what kind of a committment do you have in enforcing these guidelines.

  11. SCREAMING_CAPS is the only appropriate casing style for constants like THIRTY_ONE and SEVENTEEN.

  12. David Betz says:

    I for one am glad that SCREAMING_CAPS are illegal in _every_ case, in _every_ way and are _never_ under _any_ circumstances _ever_ to be _considered_ to even be allowed to enter a pre-thought of a brainstorm.

    Now if people could only get rid of that capitalized SELECT * FROM POORLY_WRITTEN_SQL stuff.

    The greek lowercase becamse popular for a reason! I suggest everyone watch Brad’s videos. I require all my classes to watch them. They are amazing.

  13. BradA says:

    SN – you are right, there are some places in the .NET Framework where we don’t follow our own guidelines. These are really bad and we regret everyone one of them, but some of the guidelines were still being cooked while we were developing the .NET Framework V1.0. Rest assured that we take these guidelines very seriously internally and work hard to follow them for any new APIs we create. I think you will notice that the new APIs in .NET Framework 2.0 are noticeably better as is WPF, WWF and WCF. As always, I’d love to hear your feedback on where we could be doing better.