4

因此，对于常用的东西，我有一些扩展方法，并且在记录它们时，我突然想到我不知道如何summary在 XML 注释中一致地编写标记。例如：

    /// <summary>
    ///     Gets a subset of characters from the left-hand side of a string.
    /// </summary>
    public static string Left(this string value, int length)

对比

    /// <summary>
    ///     Gets the name of the month for this date.
    /// </summary>
    public static string MonthName(this DateTime value)

所以，问题似乎是我不知道如何始终如一地引用那个讨厌的this参数。此外，我不知道如何清楚地表明这是一种扩展方法（因为我不确定 Sandcastle 和其他工具是否已经赶上它们并且可以自动注释文档以显示它）；我不想以后不得不撕掉所有的手动文档。

所以问题是，对于记录扩展方法有什么指导？如果没有正式的指导，你们都是怎么处理的？如果我们还没有，我们可以对某事进行投票，以便我有事可做吗？作为一个强迫性控制狂，这种不一致让我发疯。

4

1 回答 1

3

不支持扩展方法的 .NET 语言将要求用户直接调用该方法并传入已扩展的对象。因此，记录此参数并准确描述为什么需要它以及方法将如何作用于它是很重要的。

从扩展方法方面考虑这可能有点困难，但是如果您从另一方设想方法，人们正在调用静态方法，那就更容易了。

另一件事...有时您可能会发现自己（例如 MVC 中的 HtmlHelper）在扩展对象时超出了惯例而不是必要性。这意味着被扩展的对象是否为空并不重要，因为该方法不会对其进行操作。虽然约定（我相信）是在this对象为空时抛出，但我更喜欢让方法正常完成并在帮助中记录这一事实（即，“......这可以是空的”或“......空是此参数的有效值。”）

于 2008-12-31T19:51:09.737 回答