In the middle of a code review the other day one of the engineers turned to me and asked, “Why are all your method parameters capitalized?”
“Hmmm, well,” I told him, “that’s the Microsoft convention.”
“No, it’s not.” he replied.
And he was right.

If you are so inspired and go back to read my code in past posts it may not be obvious as I often use snippets and auto-generated code but it’s there.  This is probably even worse as it introduces an inconsistency where some of my parameters are PascalCased and others are camelCased.

Style and capitalization conventions are something we programmers often tread lightly on. Does the open curly brace go on the line with the method definition or the next line? Should closing curly brace go be lined up with the method definition or with the last line of code? We take style and conventions almost like gospel and it’s hard to let it go so we try not to point out something that we disagree with. That is why there should be some reference that all programmers can refer to either compiled by your lead architect or by some industry standard.  That way when someone suggests something is wrong with our style there can be common guideline rather than taking it personally. I know it may not seem like it but this is really critical when working in other programmers’ code. It goes to code readability and therefore ease of maintenance.

I’m not sure how or why but in the last few years I started PascalCasing my method parameters. If you check the capitalization conventions you find every public facing identifier uses PascalCasing except parameters, which uses camelCasing.

But there is more there than I realized. So for my own reference I decided to write a post about it. This is all available at the link above but presented here as a summary

1. PascalCasing, as defined by Microsoft, has the first letter upper cased.
2. camelCasing, as defined by Microsoft, has the first letter lower cased.
3. All identifiers except parameter names use PascalCasing, this includes acronyms. (HtmlTag, XmlWriter)
4. The only exception is two-letter acronyms.
   1. For PascalCasing upper case both. (IOStream)
   2. For camelCasing lower case both. (ioStream)
5. Never use an underscore in an identifier.

Where things really get into the weeds, and I’m sure I’ve violated this quite a bit is the use of compound terms.

1. Treat most compound terms as single words for purposes of capitalization. (Endpoint, metadata)
   1. There are all sorts of exceptions to this so check the reference. (LogOff, SignIn, fileName)
2. Treat a closed-form compound term as a single word. (Keyboard, crosstown)
   1. There are exceptions to this so check the reference. (UserName)

That last one especially kills me. Username is a closed-form compound term (based on both the latest Merriam-Webster and Random House Dictionary), meaning that it is treated as a single word. But according to Microsoft, for capitalization purposes, User and Name should both be capitalized.

Notable Common Terms that violate the rules or are special just because Microsoft says so (from the reference):

There are a few oddities here I wanted to point out.

1. UserName, I mentioned earlier. It’s a closed-form compound word that is not treated as a single word.
2. LogOn. I can almost understand using LogOff instead of LogOut as LogOff is a recognized compound word. But “Log On” and “Log In” are both recognized compound words. The only reason I can think to prefer LogOn to “LogIn” is to be consistant with LogOff.
   1. This also applies to SignIn/SignOut
3. Indexes. Both indexes and indices are recognized plural forms of index. Maybe just for consistancy?
4. The two letter words. I point that out because I see this a lot: Ok, ok, not OK, Id, id, not ID, Pi, pi, not PI.

Well, that’s it for now. Hopefully we can all now code to the same conventions when working in .NET.

Thanks for reading,
Brian