开发者

Conventions For Summary And Parameter Text?

开发者 https://www.devze.com 2023-02-10 22:17 出处:网络
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

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

精彩评论

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

关注公众号