摘要和参数文本的约定?

发布于 2024-10-18 01:44:21 字数 575 浏览 3 评论 0原文

对于编写摘要和参数文本,是否有最佳实践来确定您必须了解多少细节,是否使用完整的句子,或者其他什么?当我开始更多地使用这些时,我只是在寻找一些可以建立的好习惯。谢谢!

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 技术交流群。

扫码二维码加入Web技术交流群

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

评论(1

无可置疑 2024-10-25 01:44:21

我的经验法则是使用足够的细节来清楚地传达含义,而不是更多。

我更喜欢这里的简洁性 - 并且觉得这一点特别重要,因为 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.

~没有更多了~
我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。
原文