TOC

This article has been localized into Chinese by the community.

基础知识:

代码注释

在编写代码时,您将很快习惯这样一个事实,即您输入的任何字符或单词都具有特殊含义。 例如,你会在C#中看到很多keywords,比如class, namespace, public等等。 您还将看到编译器确保您以正确的方式使用这些关键字以及您自己的变量和方法。 C#是一种相当严格的语言,编译器将帮助您确保所有内容都按照应有的方式输入。 但是在代码注释里,您可以编写任何您喜欢的内容。

您可能已经在一些代码中看到过注释,无论是C#还是任何其他编程语言 - 代码中的注释概念非常普遍。 它们的编写方式各不相同,所以让我们看一下可以在C#代码中使用的注释类型。

单行注释

C#中最基本的注释类型是单行注释。 正如名称所示,它将一行转换为注释 - 让我们看看它:

// My comments about the class name could go here...
class Program
{
......

就是这样:将两个正斜杠(//)放在行首,你写的文本就从编译器将检查和报错的内容变成完全被编译器忽略的内容。 虽然这种忽略仅作用于加标记的本行,但您可以在下一行中自由地执行相同的操作,从而使用单行注释来创建多个注释行:

// My comments about the class name could go here...
// Add as many lines as you would like
// ...Seriously!
class Program
{
......

多行注释

如果您想要编写多行注释,使用C#提供的多行注释变量可能更方便。 您只需输入一个开始和结束字符序列,而不必为每一行添加前缀 - 中间的所有内容都被视为注释:

/*  
My comments about the class name could go here...  
Add as many lines of comments as you want  
...and use indentation, if you want to!  
*/  
class Program  
{
......

使用正斜杠星号(/*)的标记开始,在多行之间写下您喜欢的任何内容,然后以星号正斜杠(*/)的标记结束。 在这些标记之间,您可以编写任何您想要的内容。

与几乎任何其他与编程相关的主题一样,是否使用多个单行注释或一个多行注释通常会引起争议。 就个人而言,这两种都会使用 - 最终,这完全取决于你!

文档注释

文档注释(有时称为XML文档注释)看起来像常规注释,但使用嵌入式XML。 就像常规注释一样,它们有两种形式:单行和多行。 你也可以用相同的方式编写它们,但需要额外的字符。 因此,单行XML文档注释使用三个正斜杠(///)而不是两个,并且多行变量在开始分隔符中添加了额外的星号。 让我们看看它的样子:

class User
{
    /// <summary>
    /// The Name of the User.
    /// </summary>
    public string Name { get; set; }

    /**
    * <summary>The Age of the User.</summary>
    */
    public string Age { get; set; }
}

在这里你可以看到这两种形式 - 单行和多行。 其结果是一样的,但是第一种形式往往是最常用的文档注释。

使用文档注释记录您的类型及其成员是一个相当大的主题,将在后续章节中更深入地介绍它,但现在你知道他们的样子!

代码注释和任务列表

如果您使用的是Visual Studio,实际上可以获得一些跟踪代码注释的帮助。 在“任务列表”窗口(从菜单视图>任务列表中访问它),如果使用特殊但非常简单的任务列表注释语法,则会显示注释:

//TODO: Change "world" to "universe"
Console.WriteLine("Hello, world!");
//HACK: Don't try this at home....
int answerToLife = 42;

因此,如果单行注释后面紧跟TODO或HACK,它将出现在Visual Studio的任务列表中,如下所示:

还有更多类型 - 根据您使用的Visual Studio版本,它将响应以下部分或全部注释标记:

  • TODO
  • HACK
  • NOTE
  • UNDONE

如果您愿意,您甚至可以添加自己的令牌 - 只需按照本文中描述的步骤操作即可。

小结

代码注释在记录代码时非常有用,或者是为了向自己或潜在的同事提供有关工作原理的线索。 另外一个好处是,当您需要快速测试时,它们非常棒 - 只需复制一行并注释掉原始行,您就可以看到它现在是如何工作的。 如果您对结果不满意,可以删除新行并取消注释原始行,就回到开始的样子。

并且不要担心最终用户窥探您的注释- 如前所述,它们完全被编译器忽略,因此无论如何都不会包含在您的最终DLL或EXE文件中。 代码注释是您编程时的个人自由空间,因此请以您想要的任何方式使用它。

This article has been fully translated into the following languages: Is your preferred language not on the list? Click here to help us translate this article into your language!