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. 注释的规范
-
尽量让代码能够自解释，从而减少注释的使用；
-
用空格将注释符号和内容隔开；
-
避免多余的注释；
-
及时更新注释，没有注释比过期的注释更好；
-
英文的注释往往更好，超过一个英文单词的注释首字母应该大写并使用标点符号。
实例：
# 不好的例子
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 注解
在工作中我们会经常用到注解功能，它是我们约定的一种注释方式，用来分类并提示在工作中，我们接下来要做的一些事情。
常用的注解有下面几种：
| 关键字 | 什么时候使用 |
|---|---|
| TODO | 备注缺失的特性或者在以后添加的功能 |
| FIXME | 备注有问题需要修复的代码 |
| OPTIMIZE | 来备注慢的或者低效的可能引起性能问题的代码 |
| HACK | 备注那些使用问题代码的地方可能需要重构 |
| REVIEW | 来备注那些需要反复查看确认工作正常的代码。例如： REVIEW: 你确定客户端是怎样正确的完成 X 的吗？ |
经验：
-
注解应该写在紧接相关代码的上方；
-
注解关键字后跟一个冒号和空格，然后是描述问题的记录；
-
如果需要多行来描述问题，随后的行需要在
#后面缩进两个空格； -
注解不应该放在行尾而没有任何备注。
实例：
# 错误的实例
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来进行多行注释，了解了注释的基本规范与注解。
让我们趁热打铁继续学习下一章节。