C# VisualStudioXML注释

下面是一个例子，不必费心阅读，只需注意事情会变得多么大：

/// <summary>
/// An animated sprite is stored as one image, visually divided in
/// matrix-like form where each frame is one element. Frames are numbered
/// from 0 to some number n. The top left frame in the matrix is at (0, 0)
/// and the bottom right is at (n, n). Given a frame number this method
/// returns a position in that matrix.
/// </summary>
/// <param name="frame">Frame number.</param>
/// <returns>Matrix position.</returns>
/// <remarks></remarks>
/// <seealso cref="Book: C# Game Programming for Serious Game Creation."/>
public System.Drawing.Point GetMatrixPositionFromFrameNumber(int frame)
{
    System.Drawing.Point point = new System.Drawing.Point();
    point.Y = frame / framesX;
    point.X = frame - (point.Y * framesX);
    return point;            
}

//
///动画精灵存储为一个图像，在视觉上划分为
///矩阵形式，其中每个框架是一个元素。帧已编号
///从0到某个数字n。矩阵中左上角的帧位于（0,0）
///右下角是（n，n）。给定一个帧号，该方法
///返回该矩阵中的位置。
/// 
///帧号。
///矩阵位置。
/// 
/// 
public System.Drawing.Point GetMatrixPositionFromFrameNumber（int-frame）
{
System.Drawing.Point=新的System.Drawing.Point（）；
点Y=帧/帧X；
点X=帧-（点Y*framesX）；
返回点；
}

你们是这样评论的还是从源文件中得到评论的

---

谢谢你

中国有句古老的谚语说：“评论越接近代码，就越好。”

我对它的长度并不感到惊讶

---

您可以稍后使用sancastle或其他工具从源代码中提取这些信息。

我使用的是Ghost文档或Visual Studio摘要，如果它们太大，我会将它们折叠起来。不过，我倾向于更简洁地说明我在其中的内容，希望读者能够从方法名称和其他注释或代码中推断出该方法的一些含义。

在评论方面，我是相当一致的。一般来说，我会：

/// <summary>
/// Creates an instance of <see cref="ITemplate"/> from the specified string template.
/// </summary>
/// <typeparam name="T">The model type.</typeparam>
/// <param name="razorTemplate">The string template.</param>
/// <param name="model">The model instance.</param>
/// <returns>An instance of <see cref="ITemplate"/>.</returns>
ITemplate CreateTemplate<T>(string razorTemplate, T model);

//
///从指定的字符串模板创建的实例。
/// 
///模型类型。
///字符串模板。
///模型实例。
///一个例子。
ITemplate CreateTemplate（字符串razorTemplate，T模型）；

其中，

表示操作的摘要。在需要提供更清晰的信息或解释预期行为的情况下，我使用

：

//
///测试独立模板服务不能使用与应用程序相同的应用程序域
///主要应用领域。
/// 
/// 
///隔离模板服务将在Dispose上卸载其子应用程序域。我们需要确保
///它不会尝试卸载正在运行的当前应用程序域。这可能还是可能
///不是主要的应用领域（但很可能是）。
/// 
[测试]
使用MainAppDomain（）时，公共void IsolatedTemplateService_将通过wexException_
{
Assert.Throws（（）=>
{
使用（var服务=新的IsolatedTemplateService（（）=>AppDomain.CurrentDomain））
{ }
});
}

我不认为方法中的行数对XML注释的大小有任何影响

通常，XML注释是针对公共成员的，因此该代码的使用者不知道内部工作是什么，因此他们不会关心该方法是1行还是100行长。他们记录了行为和用法，同样，与幕后代码的数量无关

---

有时很难确定要提供多少信息，但是，您的示例似乎太长，而且通常有一些方法可以减少评论中需要提供的信息量。更具描述性的方法名称、为方法提供重载、更多的类和更少的责任等等。

这不适合程序员使用吗。stackexchange.com。。这不是一个问题，伙计们，你们评论哪怕是一行的方法吗？我对评论很敏感，所以除了字段，我什么都评论。公共API它非常重要，但对于私有方法，它在其他人维护代码时非常有用。

/// <summary>
/// Tests that an isolated template service cannot use the same application domain as the 
/// main application domain.
/// </summary>
/// <remarks>
/// An isolated template service will unload it's child application domain on Dispose. We need to ensure
/// it doesn't attempt to unload the current application domain that it is running in. This may or may
/// not be the main application domain (but is very likely to be).
/// </remarks>
[Test]
public void IsolatedTemplateService_WillThrowException_WhenUsingMainAppDomain()
{
    Assert.Throws<InvalidOperationException>(() =>
    {
        using (var service = new IsolatedTemplateService(() => AppDomain.CurrentDomain))
        { }
    });
}