Visual Studio的XML註釋

下面是一個例子，也懶得看它只是注意到的東西有多大可以得到：Visual Studio的XML註釋

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

你這樣的傢伙發表評論或者你以某種方式獲取評論你的源文件？

謝謝

來源

2011-08-25 pokoko222

心不是這個適合programmers.stackexchange.com ..其NT問題PerSay的 – Baz1nga

難道你們連註釋一行的方法呢？ – pokoko222

當談到評論時，我非常肛門，所以我評論除字段以外的所有內容。公共API是非常重要的，但是對於私有方法，當其他人維護代碼時它很有用。 –

有一個古老的中國諺語說：「越接近的註釋是代碼，越好」。

我對長度並不感到驚訝。

您可以稍後使用sancastle等工具從源代碼中提取此信息。

來源

2011-08-25 12:34:40

我使用的是Ghost Doc或Visual Studio摘要，如果這些摘要太大，我將它們摺疊。儘管如此，我傾向於更加簡潔地介紹我的內容，希望讀者從方法名稱以及可能的其他評論或代碼中推斷出該方法的一些含義。

來源

2011-08-25 12:35:05 mtijn

當談到評論時，我非常一致。一般來說，我會做：

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

來源

2011-08-25 12:35:32

我不相信一個方法中線路的數量應該對XML的大小有任何影響註釋。

通常，XML註釋是針對公共成員的，因此該代碼的使用者不知道內部工作是什麼，所以他們不會在意方法是1行還是100行。它們記錄諸如行爲和用法之類的東西，再次，與幕後代碼量無關。

有時可能很難確定要提供多少信息，您的示例似乎過於冗長，並且通常有方法可以減少評論中需要提供的信息量。更具描述性的方法名，提供以下方法重載，更多的類用更少的責任等

來源

2011-08-25 12:53:13 RichK

Visual Studio的XML註釋

回答

相關問題