摘要和参数文本的约定?
对于编写摘要和参数文本,是否有最佳实践来确定您必须了解多少细节,是否使用完整的句子,或者其他什么?当我开始更多地使用这些时,我只是在寻找一些可以建立的好习惯。谢谢!
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){
...
}
}
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
/// </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){
...
}
}
如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。

绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱,如果其他用户或者作者回复了您的评论,将不能在第一时间通知您!
发布评论
评论(1)
我的经验法则是使用足够的细节来清楚地传达含义,而不是更多。
我更喜欢这里的简洁性 - 并且觉得这一点特别重要,因为 XML 文档用于智能感知。很长的注释往往不容易被看到,所以我会避免它们,并在需要时将“较长”的注释放入
中。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.