注释是给开发人员看的，很多地方不复杂的功能就没有必要写注释了。

去翻看了几个 model 文件，觉得都太简单了，不用注释了吧。

好吧，我是菜鸟，还需要进步一熟悉....默念

往往是不知道代码是干嘛的才要写注释吧，你把环境配起来，本地运行下网站，主要功能走一圈，这就是图形化注释哇，可遇而不可求。只有那些 gem 才需要写注释。

看 github 程序员的文章知道了这个东西 http://tomdoc.org/

如果 ruby-china 要走鼓励二次开发的道路，加上注释是好的。

个人认为注释 是个好习惯 只是因为各种原因 还没做到

注释很容易跟不上代码的重构节奏。

我认为把每个函数写的简短一些，就不用写注释了。

@Rei http://tomdoc.org/ 这个有点意思

http://tomdoc.org/ 或许可以考虑用这个

#5 楼 @Rei 谢谢分享，非常有趣的文档工具。

真正要写注释的地方是比较少的（比如各种 API，就比较有必要），其它的所谓需要写注释的地方很多可以通过 extract method 来解决

#11 楼 @fsword “代码即注释”，呵呵

我喜欢用 http://yardoc.org/ ：）

单元测试也许是最好的文档了。

其实吧，一般的程序员都很懒的，在没有获取使用者任何报酬的情况下没有义务让大家读得那么轻松，自己明白在干什么就好了，即使有的注释也主要为自己服务。既然是开源的，欢迎广大使用者把注释加上然后提上去，作者会很乐意 merge 的，哇哈哈

建议大家看看.... github 是怎么做的... http://zachholman.com/talk/ruby-patterns

我非常赞同 holman 的说法....

没有什么代码比母语看起来更直接...even ruby...

#3 楼 @jokry and #4 楼 @clc3123

有两种情况需要写代码注释：

1. 这段代码提供的是公共的 API（主要介绍用法，参数，返回值什么的）
2. 代码的逻辑无法一眼看懂

以 Rails 的一段代码为例（来自 active_support/core_ext/array/grouping.rb）

# Splits or iterates over the array in groups of size +number+,
# padding any remaining slots with +fill_with+ unless it is +false+.
#
#   %w(1 2 3 4 5 6 7).in_groups_of(3) {|group| p group}
#   ["1", "2", "3"]
#  省略部分内容....

def in_groups_of(number, fill_with = nil)
  if fill_with == false
    collection = self
  else
    # size % number gives how many extra we have;
    # subtracting from number gives how many to add;
    # modulo number ensures we don't add group of just fill.
    padding = (number - size % number) % number
    collection = dup.concat([fill_with] * padding)
  end
  # 省略部分代码
end

最上方的注释属于第一类，中间部分的注释则是第二类。像 ruby-china 这种项目，本身没有提供什么公共模块，也不涉及特别复杂的逻辑，注释少是比较正常的吧～～

#5 楼 @Rei

TomDoc 这只是个注释风格约定么？

#17 楼 @iwinux 只是个风格。我还真试过想写文档了结果不知道要按什么格式写。