我一般不写注释... 能用代码表达清楚的绝不写注释。需要写文档才能说清的绝不用注释凑合。

#1 楼 @5long 回头看以前代码的时候没有觉的累过？

code tells how, comment explains why.

代码所呈现的是：以什么样的方式，完成了什么功能 注释所补充的是代码无法呈现的信息，比如“为什么要这样”，“为什么要以这种方式”

如果注释在描述“做了什么”，是一种代码坏味道，因为说明代码不够清晰了，就会导致

回头看以前代码的时候觉的累

以这种思路去实践，开发时更多的是代码重构，而不是加注释。

#3 楼 @dotnil 一句话概括了我的一段话，精辟

似乎是说 要写注释的时候就意味着需要定义新方法明晰功能 反正我看到过一段代码处理系统兼容的看不懂只有一行注释.. #here be dragons

#3 楼 @dotnil 赞同～

#3 楼 @dotnil @qhwa shopqi 就写了注释，代码也足够清晰，注释本来的功能就是帮助阅读和理解代码，有注释可能是会有坏味道，但是没有注释也不一定就一点儿坏味道就没了啊，在重构代码的时候如果有注释还可以帮助自己发现坏味道，我认为写注释只有好处，不会有坏处

#3 楼 @dotnil code tells how, comment explains why.这个我也赞同，可是现状是大部分项目一句注释都木有。。。。

#8 楼 @ghjcumt2008 怎么会没有坏处呢？注释本身无法测试，注释可能与代码同义，而我们知道，重复是万恶之源

#10 楼 @fsword 注释又不是代码逻辑，是辅助理解阅读代码的，又不会影响代码效率，又不会影响响应时间，重复是万恶之源不同地方相同逻辑的叫代码重复，为了更好理解代码的注释怎么能叫重复呢

#9 楼 @ghjcumt2008 见仁见智吧，或许人家项目浑然天成，一点奇葩代码都没有，绝对一目了然呢……

写代码时，应该多想想怎么写才能把注释删掉

习惯代码里一堆注释的，以前应该是看了不少 Apache 协议的代码吧...

又来了，以前提倡写代码必须写注释，后来提出使代码能直接表达其意（特别是像 ruby 这样强表达力的），然后就干脆啥注释都不写了。

每个人（团队）都有自己的原则，我的原则是尽量少些，用代码表达，当然一定会有那些有注释更便于理解的时候就写点。

#14 楼 @luikore 做 java 项目比较多，看一句注释都没有的代码，还是有点儿不习惯

#16 楼 @ghjcumt2008 很多 java 开源项目是 Apache 协议，Apache 协议要求每个源文件开头都要带 license, 而 github 上的 ruby 项目多是 BSD 或者 MIT, 注释量大减 XD

ruby 程序员都是看测试用例的，你搞错方向了

#18 楼 @xds2000 恩，意识到了，要先从测试用例看起，不过最后还是要看到 MVC 代码里去的，于是此问题就出来了

#18 楼 @xds2000 我接触 rails 时间不长，现在写 Rspec 测试，一到 describe 就愣半天，心想怎么组织语言让这一段段的连成句子。

#3 楼 @dotnil 精辟

我觉得注释还是有必要的。 尤其是那些关于具体 业务 的代码，靠逻辑根本解释不清楚，这时候最好有注释，最起码也要标明当时写的文档的位置吧，要不然下个程序员脑袋想炸也不知道它们为什么会这样。 亲身经历。

#22 楼 @zgm 顶一个，终于有人支持我了，泪奔~~~

凸显命名的重要性。

#8 楼 @ghjcumt2008 我说的是：在注释里面描述对应的代码在做什么，是一种坏味道

没人说不需要注释。但在你开始注释之前，再审视一遍。

https://github.com/bbatsov/ruby-style-guide#comments http://blog.csdn.net/horkychen/article/details/6322152

接下来的讨论希望能有代码范例，否则很空的。

我们就以 shopqi 为例，纯粹技术探讨哈

https://github.com/saberma/shopqi/blob/master/app/models/shop.rb#L193

after_destroy do # 删除对应的目录
  FileUtils.rm_rf self.path
  FileUtils.rm_rf self.public_path
end

protected
def init_valid_date
  self.deadline = Date.today.advance months: 1 unless self.plan_free?
end

def init_currency
  self.currency ||= 'CNY' # 初始化为人民币
  set_currency_format
end

def set_currency_format # 设置币种显示格式
  data = KeyValues::Shop::Currency.find_by_code(currency)
  self.money_with_currency_format           = data.html_unit
  self.money_format                         = data.html
  self.money_with_currency_in_emails_format = data.email_unit
  self.money_in_emails_format               = data.email
end

这里 3 个注释都在解释代码做了什么，说明有优化的空间

我会这样改：

after_destroy :rm_directories

protected

  def rm_directories
    FileUtils.rm_rf self.path
    FileUtils.rm_rf self.public_path
  end

  def init_valid_date
    self.deadline = Date.today.advance months: 1 unless self.plan_free?
  end

  def init_currency
    self.currency ||= 'CNY'
    set_currency_format
  end

  def set_currency_display_format
    data = KeyValues::Shop::Currency.find_by_code(currency)
    self.money_with_currency_format           = data.html_unit
    self.money_format                         = data.html
    self.money_with_currency_in_emails_format = data.email_unit
    self.money_in_emails_format               = data.email
  end

  # 这里用 alias_method 向前兼容
  alias_method :set_currency_format, 
               :set_currency_display_format

最后一个注释是解释 为什么

#26 楼 @qhwa 如果是我，set_currency_format 这个方法就不改名了，因为本来的表意已经很清晰了。 BTW，原注释“设置币种显示格式”不太准确，这里的意思应该是“设置币种展现格式"，如果我猜的没错，这段代码的返回结果可能用于多种场合，未必仅仅是显示在界面上

偏题一下：如果是我，set_currency_format 应该移出 model，放到 decorator 里。:)

#26 楼 @qhwa 赞一个，看了那两篇文章然后回想一下自己以前写注释的方法，确实值得商榷，值得改进，不过还是呼吁一下能顺手就写个解释为什么的注释就尽量写一下，方便以后别人读代码嘛

注释是弥补以前的语言过于面向技术实现，自解释不足。 Ruby 这样的语言，如果需要大量注释，一定是程序写得太离奇了……

没必要大量写注释的 第一 写这段代码的原因可以写在 git commit message 里。第二 公司项目一般还有 ticket 管理工具，可以把更详细的文档写在 ticket 里，然后在注释里或是 git commit message 里引用。 大规模写注释的方法早就走进历史了。。LZ 老了。。

这不是一个人的问题，都是这样，刚开始也有这样的疑问，但现在习惯了，写了注释都会删掉，因为在 ruby 代码中出现 注释 真的影响美观啊，看着就不爽

#31 楼 @iBachue

#32 楼 @ginchenorlee 美观和易读我会选择易读

#34 楼 @ghjcumt2008 你还是没理解问题的关键。注释不是免费的，它需要维护，如果它和代码一同演化，那么这是维护人员的负担，而如果它不幸没有和代码一同演化（这是最大的可能），那几乎就是误导了。而且，由于注释不能被测试（所以没法用测试用例保护），后来的维护者如果没有把握，是不敢随便修改注释内容的，这使得问题变得更纠结。

这么说并不是要完全取消注释，但是你必须认识到——注释有成本，使用需谨慎

#35 楼 @fsword 大赞

我也不习惯写注释。 但是最近发现写 api 接口时如果加注释用来生成 api 文档更方便一点。

简单的地方一般懒得写注释，不过逻辑性强的地方就会写了

#35 楼 @fsword 我见过几次改了代码没改注释的情况，偏偏那个注释还写了这个方法的调用方式，结果浪费了一些时间在上面，最后发现代码已经变了……

有时看不懂老外的代码更多的是因为语言障碍，而不是没写注释。 老外读代码就跟读小说一样，绝大部分的国内程序员恐怕都做不到。

做了 N 年维护的人来说说，注释这东西，写的多了，不维护，就是各种坑，代码写到不需要注释，才是关键，对于关键的接口方法，需要有详细的注释，详细的使用说明，和各种情况的说明，我是很不推荐在代码中间放太多的注释的

#40 楼 @hpyhacking 要做到不难啊 工作一年就可以做到了 计算机英语比普通的日常英语容易多了

#42 楼 @iBachue 计算机英语才占多少

#40 楼 @hpyhacking 代码读多了都会速度快的 这只是个熟练工的问题 不是技术水平上的问题

当然要写注释！并且很多情况下代码是不能说明问题的！几种状况：

• 业务代码。代码本身阐述的是做什么，很多时候需要介绍清楚代码为什么做这个事情。这个时候需要注释。单独的函数可以放在函数上面，复杂的功能还需要整理一个 wiki，然后在代码里面加上 wiki 的链接。
• workaround。针对一些 bug 或者问题的修正，看代码是说不清楚的，需要加上 bug 号。
• 有背后的技术底蕴。比如利用到了 etags 或者浏览器的一些特性，一行代码能够解决，但是写的时候查阅了很多资料，这个时候要把思考过程附上让后来人能够理解这个代码后面的事情。

注释应该怎样写

解释做了什么

# 把选项设为真
option = false

解释为什么这样做

# 网上拷过来的
print "hello world"

修复 bug

# 修复 method missing 的 bug
class Object
  def method_missing *args
  end
end

技术背景

# 请阅读 Intel x86 手册
code << "\x55\x8B\xEC"\
        << function_body\
        << "\x5D\xC3"

Proof of work

# 如果作了修改, 请也更改下一行的数字, 以保证这个源文件的 SHA2 摘要的末 64 bit 为 0
# 20391
...

注释是需要重构的线索之一