Ruby 注释

注释是 Ruby 代码中的标注，在执行时会被 Ruby 解释器忽略。它们对于解释代码中的复杂部分、为自己或其他开发者留下笔记或临时禁用代码行至关重要。

单行注释

单行注释以井号 (#) 开头，并持续到该行的末尾。该行 # 之后的所有内容都被视为注释。

#!/usr/bin/env ruby

# 这是一个单行注释。
puts "Hello, Ruby!"  # 这是一个行尾注释，解释了 'puts' 行。

# 另一行单独的注释。
# x = 10  # 这一行代码被临时禁用 (注释掉了)。

执行上述程序后，输出如下：

Hello, Ruby!

多行注释 (块注释)

Ruby 提供了一种使用 =begin 和 =end 编写多行注释的方式。这些标记必须位于各自行的最开头，前面不能有任何空白字符。

#!/usr/bin/env ruby

puts "Hello, Ruby!" # 这一行将被执行。

=begin
这是一个多行注释。
它可以跨任意多行。
=begin 和 =end 之间的所有行都会被忽略。
这通常用于较长的解释或注释掉大块代码。
=end

puts "This line is after the multiline comment." # 这一行也将被执行。

执行程序后，输出如下：

Hello, Ruby!
This line is after the multiline comment.

注释的最佳实践

**清晰胜于数量：**编写注释是为了解释 为什么 做某件事，或澄清复杂的逻辑，而不仅仅是代码 做什么 (这应该从写得好的代码本身就能看出来)。
**保持注释更新：**如果您更改了代码，请务必更新任何相关的注释。过时的注释可能比没有注释更具误导性。
**行尾注释：**谨慎使用行尾注释 (在代码行末尾) 来进行简短说明。如果在块中使用，确保它们对齐良好以提高可读性。
**注释掉代码：**在调试期间使用注释临时禁用代码块。请记住稍后删除或恢复这些代码。
**文档注释 (RDoc/YARD)：**对于更正式的文档 (例如，用于库或 API)，Ruby 使用约定，其中可以通过工具 (如 RDoc 或 YARD) 处理特殊格式的注释 (通常以 ## 开头) 来生成文档。这超出了基本注释的范围，但对于大型项目很重要。

对齐行尾注释的示例：

class Config
  @max_users = 100    # 最大并发用户数
  @timeout   = 30     # 会话超时时间 (秒)
  @retries   = 3      # 失败操作的重试次数
end

有效的注释使您的代码对您自己和其他人来说更容易理解和维护。