What's the best way to communicate the purpose of a string parameter in a public API? - Printable Version +- 0Day Forums (https://0day.red) +-- Forum: Coding (https://0day.red/Forum-Coding) +--- Forum: FrameWork (https://0day.red/Forum-FrameWork) +--- Thread: What's the best way to communicate the purpose of a string parameter in a public API? (/Thread-What-39-s-the-best-way-to-communicate-the-purpose-of-a-string-parameter-in-a-public-API) |
What's the best way to communicate the purpose of a string parameter in a public API? - karl488129 - 07-20-2023 According to the guidance published in [New Recommendations for Using Strings in Microsoft .NET 2.0][1], the data in a string may exhibit one of the following types of behavior: 1. A non-linguistic identifier, where bytes match exactly. 1. A non-linguistic identifier, where case is irrelevant, especially a piece of data stored in most Microsoft Windows system services. 1. Culturally-agnostic data, which still is linguistically relevant. 1. 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][2]. 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&lt;string&gt; object held by the dictionary to perform, for example, a case-insensitive ordinal comparison? [1]: [To see links please register here] [2]:[To see links please register here] RE: What's the best way to communicate the purpose of a string parameter in a public API? - Mrcorrelatively546 - 07-20-2023 Use the documentation syntax: /// <param name="dictionary"> /// ... string is case sensitive ordinal ... /// </param> RE: What's the best way to communicate the purpose of a string parameter in a public API? - lobules662236 - 07-20-2023 You could always use a modified Hungarian convention (and I mean the [Joel-approved kind][1]): * 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. [1]: [To see links please register here] |