Ruby脚本注释怎么写：实用技巧与常见用法

写ref="/tag/2028/" style="color:#874873;font-weight:bold;">Ruby脚本时，加注释是个好习惯。别小看那几行不起眼的文字，回头翻代码的时候，它能让你一秒明白当初为啥这么写。尤其是一些逻辑绕的判断或者正则表达式，没注释简直就是天书。

单行注释用 #

最常见的就是用井号（#）来写单行注释，它后面的内容都会被Ruby忽略。

# 检查用户是否成年
if age >= 18
  puts "可以进入"
end

这种写法简单直接，适合解释某一行或接下来的一小段代码是干啥的。

多行注释可以用 =begin 和 =end

虽然不常用，但Ruby也支持块注释。用 =begin 开头，=end 结尾，中间的内容全算注释。

=begin
这个方法用来计算折扣价
传入原价和折扣率
返回打折后的金额
=end

def calc_discount(price, rate)
  price * (1 - rate)
end

注意：=begin 和 =end 必须独占一行，而且顶格写，前面不能有空格，否则无效。

文档注释推荐用 RDoc 风格

如果你写的脚本以后可能被别人调用，或者你自己想生成文档，可以用RDoc风格的注释。它通常写在方法或类的前面，用普通#开头，但格式更规范。

# 计算商品总价
#
# @param [Array<Float>] prices 商品价格列表
# @return [Float] 总金额
# @example
#   total([10.5, 20.0, 5.5]) # => 36.0
#
def total(prices)
  prices.sum
end

这种写法看着像多写了几行，但工具能自动提取生成网页文档，团队协作时特别有用。

注释不是越多越好

见过那种每行都写注释的代码吗？反而更难读。比如：

# 设置变量x为5
x = 5
# 输出x的值
puts x

这种就纯属多余。注释的重点是“为什么”，而不是“是什么”。代码自己能说清楚的部分，不用重复。

实际场景举例

假设你写了个定时脚本，每天清理日志文件，里面有这么一段：

# 只保留最近7天的日志，避免磁盘爆满
Dir.glob("logs/*.log").each do |file|
  if File.mtime(file) < (Time.now - 7*24*60*60)
    File.delete(file)
  end
end

加上这句注释，下次你或者同事看到就知道：哦，这是防磁盘被撑爆的保险措施，不能随便删。

写Ruby脚本时，顺手把想法记下来，花不了几秒，但省下的可能是半小时的回忆时间。