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.
精彩评论