What's the best way to communicate the purpose of a string parameter in a public API?

Question

According to the guidance published in New Recommendations for Using Strings in Microsoft .NET 2.0, the data in a string may exhibit one of the following types of behavior:

1. A non-linguistic identifier, where bytes match exactly.
2. A non-linguistic identifier, where case is irrelevant, especially a piece of data stored in most Microsoft Windows system services.
3. Culturally-agnostic data, which still is linguistically relevant.
4. Data that requires local linguistic customs.

Given that, I'd like to know the best way to communicate which behavior is expected of a string parameter in a public API. I wasn't able to find an answer in the Framework Design Guidelines.

Consider the following methods:

   f(string this_is_a_linguistic_string)
   g(string this_is_a_symbolic_identifier_so_use_ordinal_compares)

Is variable naming and XML documentation the best I can do? Could I use attributes in some way to mark the requirements of the string?

Now consider the following case:

   h(Dictionary<string, object> dictionary)

Note that the dictionary instance is created by the caller. How do I communicate that the callee expects the IEqualityComparer<string> object held by the dictionary to perform, for example, a case-insensitive ordinal comparison?

Answer 1

Use the documentation syntax:

/// <param name="dictionary">
/// ... string is case sensitive ordinal ...
/// </param>

Answer 2

You could always use a modified Hungarian convention (and I mean the Joel-approved kind):

• Prefix cs for case-sensitive (non-linguistic)
• Prefix ci for case-insensitive (non-linguistic)
• Prefix cil for culture-invariant linguistic
• Prefix csl for culture-specific linguistic or culture-sensitive linguistic

The "i" and "s" have consistent implications here, even though they can mean two different things depending on the context, which is a helpful attribute. "i" means "don't care" (about case/culture) and "s" means "do care".

Of course, as a disclaimer, I never do this, because for the vast majority of strings I deal with, the distinction between these types of strings is blurry at best. But if they have semantic meaning to you, this would be a reasonable alternative to relying on XML docs. Especially when you're using them as arguments to private methods, which most people don't write XML docs for.