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

• Anonymous
  August 24, 2004
  great idea
• Anonymous
  August 24, 2004
  The comment has been removed
• Anonymous
  August 26, 2004
  Very good point. Thanks for the light.
• Anonymous
  August 30, 2004
  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.