通过

Framework Design Guidelines: Naming New Versions of Existing APIs

  • 项目

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.

Comments

  • Anonymous
    December 08, 2008
    By the way, while only have the first version of Framework Design Guidelines, this topic reminds me of something in them that is somewhat related... The use of the "2" suffix when you have a term that cannot really change, and need to evolve it anyway... let say "DateTime2". Its rarely used, rarely needed, but as the various platforms evolve, its starting to pop every so often, and I'm wondering if thats really for the best... it is honestly seriously confusing, and I'm wondering if there isn't anything better we could think of... Its a bit of a stretch on the topic of this post, I know, but I still think its relevent :)

  • Anonymous
    December 09, 2008
    Hmm.. I don't like any suffixes like "64" or "2". Imagin, you create "64"suffixed API functions (and new API without any suffixes, as you said). So in 2-3-5 years you are going have only 64 bit platform and all the "64"suffixed functions. "64" is meaningless in this situation, it is just a trash in the methods names. Especially if you created "new" API without any suffixed. Mix is always bad ;) So what the solution? If we are talking about reusable frameworks, we can create factories/adapters/interfaces for 32 and 64 bit systems. Want to use 64bit? Use 64bit API interfaces, don't worry about 32bit, you will not even see 32bit methods. Why on earth I need to see PeakWorkingSet on 64bit or PeakWorkingSet64 on 32bit? If not all the functions are suffixed, when I see PeakWorkingSet, how can I know if it is a "new" 64bit API, or an "old" 32bit? So my point is to make specific APIs for the specific environments, even if they reuse the same code internally, as a developer who used this API, I don't care :)

  • Anonymous
    December 09, 2008
    i  want to  be a friend  to u .

  • Anonymous
    December 11, 2008
    Good show!! I recently started a blog of mine. I would love it if you would add me to your blog roll and vice verse. http://luscious69.blogs

  • Anonymous
    December 15, 2008
    But what about Array.GetLongLength() ... ?