在公共 API 中传达字符串参数用途的最佳方式是什么？

Question

根据New Recommendations for Using Strings in Microsoft .NET 2.0 中发布的指南，字符串中的数据可能会表现出以下行为类型之一：

1. 一个非语言标识符，其中字节完全匹配。
2. 一种非语言标识符，与大小写无关，尤其是存储在大多数 Microsoft Windows 系统服务中的一段数据。
3. 与文化无关的数据，在语言上仍然具有相关性。
4. 需要当地语言习惯的数据。

鉴于此，我想知道在公共 API 中传达字符串参数的预期行为的最佳方式。我无法在Framework Design Guidelines 中找到答案。

考虑以下方法：

   f(string this_is_a_linguistic_string)
   g(string this_is_a_symbolic_identifier_so_use_ordinal_compares)

变量命名和 XML 文档是我能做的最好的吗？我可以用某种方式使用属性来标记字符串的要求吗？

现在考虑以下情况：

   h(Dictionary<string, object> dictionary)

请注意，字典实例是由调用者创建的。我如何传达被调用者期望字典持有的 IEqualityComparer 对象执行例如不区分大小写的序数比较？

Answer 1

使用文档语法：

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

Answer 2

您总是可以使用修改后的匈牙利语约定（我的意思是Joel-approved kind）：

• 前缀cs 表示区分大小写（非语言）
• 前缀ci 表示不区分大小写（非语言）
• 前缀cil 表示文化不变的语言
• 前缀csl 用于文化特定语言或文化敏感语言

“i”和“s”在这里具有一致的含义，即使它们根据上下文可以表示两种不同的东西，这是一个有用的属性。 “i”表示“不关心”（关于案例/文化），“s”表示“关心”。

当然，作为免责声明，我从不这样做，因为对于我处理的绝大多数字符串，这些类型的字符串之间的区别充其量是模糊的。但是，如果它们对您具有语义意义，那么这将是依赖 XML 文档的合理替代方案。尤其是当您将它们用作私有方法的参数时，大多数人不会为此编写 XML 文档。