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>如果需要的话。