开发者

Conventions For Summary And Parameter Text?

For writing summary and parameter text, is there a best practice for how much detail you have to get into, whether or not to use complete sentences, or whatever? I'm just looking for some good habits to establish as I start using these more. Thanks!

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

    /// <summary>
    /// JustinBieber object sings a song in specified style
    /// 开发者_如何学JAVA</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){
        ...
    }
} 


My rule of thumb here is to use enough detail to convey the meaning clearly, and no more.

I prefer conciseness here - and feel this is particularly important, as the XML documentation is used for intellisense. Very long comments tend to not be visible easily there, so I would avoid them, and put the "longer" comments into <remarks> if needed.

0

上一篇:

下一篇:

精彩评论

暂无评论...
验证码 换一张
取 消

最新问答

问答排行榜