服务端相关 / 04 Ruby 的注释

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 注解

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

常用的注解有下面几种:

关键字 什么时候使用
TODO 备注缺失的特性或者在以后添加的功能
FIXME 备注有问题需要修复的代码
OPTIMIZE 来备注慢的或者低效的可能引起性能问题的代码
HACK 备注那些使用问题代码的地方可能需要重构
REVIEW 来备注那些需要反复查看确认工作正常的代码。例如: REVIEW: 你确定客户端是怎样正确的完成 X 的吗?

经验:

  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来进行多行注释,了解了注释的基本规范与注解。

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