Parameter naming and the Google test

Brad has a post on choosing parameter names for overloaded methods which brings to mind a recent question on an internal mailing list about using acronyms for parameter names.

In general, when determining whether or not it’s reasonable to use an acronym to name a parameter, we ask whether or not the acronym will be well known to most people using the API. This is often difficult to answer though, so we will search for the acronym on Google – if one of the top five hits is a page that explains or describes the acronym then we consider that the acronym will be reasonably well known. Otherwise we tend to suggest that the parameter name be renamed or the acronym be fully spelled out.

A recent example was for a parameter named Upn of type string. When searching for Upn on Google, the top ten hits are comprised mostly of pages linking to the TV network UPN. When you search for the fully spelled out name, “universal principal name”, the first result is a link to a glossary page on MSDN that provides a link to a definition of ‘Universal Principal Name’.

When thinking about naming parameters, types etc, we try to think of how developers will use these names. Very often the names are the first thing that people search for in Google or other search engines. We want to make sure that our names are as expressive as possible and will quickly lead people to understanding the correct usage, whether that be through intuition or through being led quickly to the correct documentation.

Comments (5)

  1. ShadowChaser says:

    I really agree with this… I thought for awhile there Microsoft was trying to have unfriendly search terms 🙂

    I mean, ".NET" is probably the second most unfriendly search term you could *ever* pick.. after ".COM" that is 🙂 Oh wait! They already did choose that one, LOL! Hopefully you guys arent secretly working on an inter-organization protocol called "ORG"

    C# is pretty bad too, but I guess C++ was even worse, so I can’t complain too much 🙂 *grin*

    The Linux guys love naming things in circular acronyms, but I think the Microsoft guys love making evil search terms. I think the MSDN team must do that so we need to use their search page *grin*

  2. Very good point. Thanks for the light.

  3. anon says:

    One more thing to bear in mind when using acronyms is their temporal nature. Acronyms go in and out of fashion very quickly. For example, ten years ago, DOS would be properly mean Disk Operating System, now it is more likely associated with Denial Of Service. If you are going to use acronyms make sure it is clearly spelled out in the documentation.