[英]What's the best way to communicate the purpose of a string parameter in a public API?
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: 根据在Microsoft .NET 2.0中使用字符串的新建议中发布的指南, 字符串中的数据可能表现出以下行为之一:
Given that, I'd like to know the best way to communicate which behavior is expected of a string parameter in a public API. 鉴于此,我想知道在公共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? 我能做的就是变量命名和XML文档吗? 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? 如何传达被调用者希望字典保存的IEqualityComparer <string>对象执行例如不区分大小写的序数比较的信息?
Use the documentation syntax: 使用文档语法:
/// <param name="dictionary">
/// ... string is case sensitive ordinal ...
/// </param>
You could always use a modified Hungarian convention (and I mean the Joel-approved kind ): 您可以始终使用经过修改的匈牙利约定(我的意思是指Joel批准的一种 ):
cs
for case-sensitive (non-linguistic) 区分大小写 (非语言)的前缀cs
ci
for case-insensitive (non-linguistic) 前缀ci
, 不区分大小写 (非语言) cil
for culture-invariant linguistic 文化不变语言的前缀cil
csl
for culture-specific linguistic or culture-sensitive linguistic 前缀csl
用于特定于文化的语言或对文化敏感的语言 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”和“ s”在这里具有一致的含义,即使根据上下文它们可以表示两种不同的含义,这也是有用的属性。 "i" means "don't care" (about case/culture) and "s" means "do care". “ i”表示“不在乎”(关于案例/文化),“ s”表示“在乎”。
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. 但是,如果它们对您有语义的意义,那么这将是依赖XML文档的合理选择。 Especially when you're using them as arguments to private methods, which most people don't write XML docs for. 尤其是当您将它们用作私有方法的参数时,大多数人不会为此编写XML文档。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.