编写Ruby代码注释时需要注意的一些问题
写出自解释文档代码,然后让这部分歇息吧。这不是说着玩。
使用英文编写注释。
使用一个空格将注释与符号隔开。
注释超过一个单词了,应句首大写并使用标点符号。句号后使用一个空格
避免多余的注释。
#bad counter+=1#incrementscounterbyone
随时更新注释,没有注释比过期的注释更好。
不要为糟糕的代码写注释。重构它们,使它们能够“自解释”。(Doordonot-thereisnotry.)
注解应该写在紧接相关代码的上方。
注解关键字后跟一个冒号和空格,然后是描述问题的记录。
如果需要多行来描述问题,随后的行需要在#后面缩进两个空格。
defbar #FIXME:Thishascrashedoccasionallysincev3.2.1.Itmay #berelatedtotheBarBazUtilupgrade. baz(:quux) end
如果问题相当明显,那么任何文档就多余了,注解也可以(违规的)在行尾而没有任何备注。这种用法不应当在一般情况下使用,也不应该是一个rule。
defbar sleep100#OPTIMIZE end
使用TODO来备注缺失的特性或者在以后添加的功能。
使用FIXME来备注有问题需要修复的代码。
使用OPTIMIZE来备注慢的或者低效的可能引起性能问题的代码。
使用HACK来备注那些使用问题代码的地方可能需要重构。
使用REVIEW来备注那些需要反复查看确认工作正常的代码。例如:REVIEW:你确定客户端是怎样正确的完成X的吗?
使用其他自定义的关键字如果认为它是合适的,但是确保在你的项目的README或者类似的地方注明。