Continuing in our weekly blog post series that highlights a few of the new image5_thumb2_thumb2_thumb_thumb_thuadditions to the Framework Design Guidelines 2nd edition.. This content is found in the Naming New Versions of Existing APIs of Chapter 3: Naming Guidelines. Incrementally evolving an existing, popular API is very hard. My main take away personally from this guidelines (and Kit’s annotation) is to work hard to get it right the first time!

DO use the “64” suffix when introducing versions of APIs that operate on a 64-bit integer (a long integer) instead of a 32-bit integer. You only need to take this approach when the existing 32-bit API exists; don’t do it for brand new APIs with only a 64-bit version.

For example, various APIs on System.Diagnostics.Process return Int32 values representing memory sizes, such as PagedMemorySize or PeakWorkingSet. To appropriately support these APIs on 64-bit systems, APIs have been added that have the same name but a “64” suffix.

public class Process {
   // old APIs
   public int PeakWorkingSet { get; }
   public int PagedMemorySize { get; }

   // …
   // new APIs

   public long PeakWorkingSet64 { get; }
   public long PagedMemorySize64 { get; }
}

KIT GEORGE

Note that this guideline applies only to retrofitting APIs that have already shipped. When designing a brand new API, use the most appropriate type and name for the API that will work on all platforms, and avoid using both “32” and “64” suffixes. Consider using overloading.