摘要和参数文本的约定？

Question

对于编写摘要和参数文本，是否有最佳实践来确定您必须了解多少细节，是否使用完整的句子，或者其他什么？当我开始更多地使用这些时，我只是在寻找一些可以建立的好习惯。谢谢！

public class JustinBieber{
    private readonly bool HasTalent;
    JustinBieber(){
        HasTalent = false;
    }

    /// <summary>
    /// JustinBieber object sings a song in specified style
    /// </summary>
    /// <param name="songName">The song to be sung</param>
    /// <param name="style">The style in which the song is sung</param>
    public void SingSong(string songName, string style){
        ...
    }
} 

Answer 1

我的经验法则是使用足够的细节来清楚地传达含义，而不是更多。

我更喜欢这里的简洁性 - 并且觉得这一点特别重要，因为 XML 文档用于智能感知。很长的注释往往不容易被看到，所以我会避免它们，并在需要时将“较长”的注释放入 中。