编写Ruby代码注释时需要注意的一些问题

更新时间：2015年08月03日 11:43:30 投稿：goldensun

这篇文章主要介绍了编写Ruby代码注释时需要注意的一些问题,特别是在团队协作时好的注释能大大增加代码的可读性,需要的朋友可以参考下

    写出自解释文档代码，然后让这部分歇息吧。这不是说着玩。
    使用英文编写注释。
    使用一个空格将注释与符号隔开。
    注释超过一个单词了，应句首大写并使用标点符号。句号后使用一个空格

避免多余的注释。

  # bad
  counter += 1 # increments counter by one

随时更新注释，没有注释比过期的注释更好。

不要为糟糕的代码写注释。重构它们，使它们能够“自解释”。(Do or do not - there is no try.)

注解应该写在紧接相关代码的上方。
注解关键字后跟一个冒号和空格，然后是描述问题的记录。

如果需要多行来描述问题，随后的行需要在 # 后面缩进两个空格。

  def bar
   # FIXME: This has crashed occasionally since v3.2.1. It may
   # be related to the BarBazUtil upgrade.
   baz(:quux)
  end

如果问题相当明显，那么任何文档就多余了，注解也可以（违规的）在行尾而没有任何备注。这种用法不应当在一般情况下使用，也不应该是一个 rule。

  def bar
   sleep 100 # OPTIMIZE
  end

使用 TODO 来备注缺失的特性或者在以后添加的功能。

使用 FIXME 来备注有问题需要修复的代码。

使用 OPTIMIZE 来备注慢的或者低效的可能引起性能问题的代码。

使用 HACK 来备注那些使用问题代码的地方可能需要重构。

使用 REVIEW 来备注那些需要反复查看确认工作正常的代码。例如： REVIEW: 你确定客户端是怎样正确的完成 X 的吗？

使用其他自定义的关键字如果认为它是合适的，但是确保在你的项目的 README 或者类似的地方注明。

您可能感兴趣的文章:

Ruby
注释

详细解析Ruby中的变量
这篇文章主要介绍了详细解析Ruby中的变量,是Ruby学习中最基础的知识之一,需要的朋友可以参考下
2015-05-05
Ruby多线程库(Thread)使用方法详解
这篇文章主要介绍了Ruby多线程库(Thread)使用方法详解,需要的朋友可以参考下
2022-04-04
Ruby on Rails网站项目构建简单指南
Rails项目通过Ruby世界中的gem和rake工具来构建起来真的相当方便,这里就给大家整理了一份Ruby on Rails网站项目构建简单指南,需要的朋友可以参考下
2016-06-06
Ruby实现网页图片抓取
本文给大家分享的是个人使用ruby编写的抓取网页图片的代码，十分的简单实用，有需要的小伙伴可以参考下。
2016-04-04
详解Ruby on Rails中的mailer相关使用
这篇文章主要介绍了详解Ruby on Rails中的mailer相关使用,主要针对其相关的编程风格给出建议,需要的朋友可以参考下
2015-08-08
ruby on rails 代码技巧
对于rails的一些使用技巧的代码
2009-01-01
Ruby 迭代器知识汇总
这篇文章主要介绍了Ruby 迭代器的的相关资料，文中示例代码非常详细，供大家参考和学习，感兴趣的朋友可以了解下
2020-06-06
Ruby中的循环语句的用法教程
这篇文章主要介绍了Ruby中的循环语句的用法教程,逻辑循环语句是每门编程语言的基础,需要的朋友可以参考下
2015-05-05
在Docker中自动化部署Ruby on Rails的教程
这篇文章主要介绍了在Docker中部署Ruby on Rails的教程,Docker是当下最火的虚拟机,而本文所介绍的Ruby on Rails的部署则充分利用了Ruby中的rake这一炫酷的实现自动化的方法,需要的朋友可以参考下
2015-06-06
redis集群搭建教程及遇到的问题处理
本文主要给大家讲诉的是如何搭建redis集群的方法以及在此过程中需要注意的问题，非常不错，推荐给大家，有需要的小伙伴可以来参考下
2017-09-09