c# - 摘要和参数文本的约定？

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 文档用于智能感知。很长的评论往往在那里不容易看到，所以我会避免它们，并在<remarks>需要时放入“更长”的评论。