04 Ruby 的注释

本章节主要带大家了解注释是什么，为什么要写注释以及在 Ruby 中如何使用注释。

1. 什么是注释？

在计算机语言中，注释是计算机语言的一个重要组成部分，用于在源代码中解释代码的功用，可以增强程序的可读性，可维护性，或者用于在源代码中处理不需运行的代码段，来调试程序的功能执行。
注释在随源代码进入预处理器或编译器处理后会被移除，不会在目标代码中保留其相关信息。——官方定义

简而言之，注释文字是为了能更好地解释代码的功能，注释代码是为了让这部分代码不要运行。

那么在 Ruby 中，我们如何使用注释功能呢？

2. Ruby 中如何使用注释

这里我们要编辑 Ruby 脚本来执行这些例子。

2.1 单行注释

单行注释＃字符开始，它们从＃直到该行结束。

# 这是一个单行注释。
 
# puts "Hello, World!"
puts "Hello, Ruby!"

# ---- 输出结果 ----
Hello, Ruby!

2.2 多行注释

您可以使用 =begin和 =end 语法注释多行。

=begin
puts "I'm Peter."
puts "I'm Andrew."
=end
puts "I'm Alice"

# ---- 输出结果 ----
I'm Alice

Tips：多行注释可扩展至任意数量的行，但=begin 和 =end 只能出现在第一行和最后一行。

3. 注释的规范

1. 尽量让代码能够自解释，从而减少注释的使用；

2. 用空格将注释符号和内容隔开；

3. 避免多余的注释；

4. 及时更新注释，没有注释比过期的注释更好；

5. 英文的注释往往更好，超过一个英文单词的注释首字母应该大写并使用标点符号。

实例：

# 不好的例子
counter += 1 #increments counter by one

解释：上面的例子中，我们应该将注释符号和内容之间加一个空格。因为“increments counter by one”是一句话，所以我们应该首字母大写且末尾要加标点符号.。

# 正确的例子
counter += 1 # Increments counter by one. 

Good code is like a good joke - it needs no explanation.

好的代码就像个玩笑-不需要解释。

– Russ Olsen

3.1 注解

在工作中我们会经常用到注解功能，它是我们约定的一种注释方式，用来分类并提示在工作中，我们接下来要做的一些事情。

常用的注解有下面几种：

经验：

1. 注解应该写在紧接相关代码的上方；

2. 注解关键字后跟一个冒号和空格，然后是描述问题的记录；

3. 如果需要多行来描述问题，随后的行需要在 # 后面缩进两个空格；

4. 注解不应该放在行尾而没有任何备注。

实例：

# 错误的实例
def bar
  sleep 100 # OPTIMIZE
end

实例：

# 正确的实例
def bar
  # FIXME: This has crashed occasionally since v3.2.1. It may
  #  be related to the BarBazUtil upgrade.
  baz(:quux)
end

4. 小结

本章中，您掌握了在 Ruby 中使用#来进行单行注释、使用=begin和=end来进行多行注释，了解了注释的基本规范与注解。

让我们趁热打铁继续学习下一章节。