Question

这是一个例子，不要费心去阅读它只是注意到有多大的东西可以获得：

/// <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;            
}

你们这样评论还是以某种方式从你的源文件中得到评论？

谢谢

Answer 1

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

我对长度并不感到惊讶。

您可以稍后使用sancastle等工具从源代码中提取此信息。

Answer 2

我不相信方法中的行数应该与XML注释的大小有任何关系。

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

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

Answer 3

在评论时我非常一致。一般来说我会这样做：

/// <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);

其中<summary>表示操作的概要。在我需要提供更多清晰度或解释预期行为的情况下，我使用<remarks>：

/// <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))
        { }
    });
}

Answer 4

我正在使用Ghost Doc或Visual Studio摘要，如果那些太大，我会崩溃它们。我倾向于对我放在那里的内容更加简洁，期望读者从方法名称以及可能的其他注释或代码中推断出方法的一些含义。

Visual Studio XML注释

4 个答案: