Каков наилучший способ сообщить о назначении строкового параметра в публичном API?

Question

Согласно руководству, опубликованному в Новые рекомендации по использованию строк в Microsoft .NET 2.0 , данные в строке могут демонстрировать один из следующих типов поведения:

1. Нелингвистический идентификатор, где байты точно совпадают.
2. Нелингвистический идентификатор, где регистр не имеет значения, особенно часть данных, хранящихся в большинстве системных служб Microsoft Windows.
3. Культурно-независимые данные, которые по-прежнему актуальны с лингвистической точки зрения.
4. Данные, которые требуют местных лингвистических обычаев.

Учитывая это, я хотел бы знать, как лучше всего сообщить, какое поведение ожидается от строкового параметра в общедоступном API. Я не смог найти ответ в Руководстве по проектированию фреймворка .

Рассмотрим следующие методы:

   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

Вы всегда можете использовать измененную венгерскую конвенцию (и я имею в виду одобренный Джоэлем вид ):

• Префикс cs для с учетом регистра (неязыковой)
• Префикс ci для без учета регистра (неязыковой)
• Префикс cil для лингвистика, инвариантная к культуре
• Префикс csl для лингвистического языка для конкретных культур или лингвистического языка для различных культур

Здесь «i» и «s» имеют согласованные значения, хотя они могут означать две разные вещи в зависимости от контекста, что является полезным атрибутом. «i» означает «все равно» (о случае / культуре), а «s» означает «все равно».

Конечно, как оговорка, я никогда не делаю этого, потому что для подавляющего большинства строк, с которыми я имею дело, различие между этими типами строк в лучшем случае размыто. Но если они имеют для вас семантическое значение, это будет разумной альтернативой использованию документов XML. Особенно, когда вы используете их в качестве аргументов для частных методов, для которых большинство людей не пишут документы XML.