Visual Studio XML comments

本文关键字：comments XML Studio Visual | 更新日期: 2023-09-27 18:06:42

这是一个例子，不要费心去读它，只要注意它可以变得多么大:

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

你们是这样注释还是从源文件中获取注释?

谢谢

Visual Studio XML comments

中国有句古话:"注释越接近代码越好。"

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

您可以稍后使用诸如sanccastle之类的工具从源代码中提取这些信息，否则

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

一般来说，XML注释是针对公共成员的，因此该代码的消费者不知道内部工作是什么，因此他们不会关心方法是1行还是100行。它们记录了诸如行为和使用之类的东西，与幕后的代码量无关。

有时候很难确定要给出多少信息，尽管你的例子看起来太长了，但通常有方法可以减少注释中需要给出的信息量。更具描述性的方法名，为方法提供重载，更多的类，更少的责任等

在评论方面我是相当一致的。一般我会这样做:

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

我使用Ghost Doc或Visual Studio摘要，如果它们太大，我会折叠它们。我倾向于更简洁地描述我在那里写的东西，希望读者能从方法名和其他可能的注释或代码中推断出方法的一些含义。

相关文章：