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.