编写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 或者类似的地方注明。

赞 (0)

相关推荐

  • 解读Ruby中注释的使用方法

    Ruby行内注释的代码在运行时被忽略.单行注释#字符开始,他们从#到行末如下: #!/usr/bin/ruby -w # This is a single line comment. puts "Hello, Ruby!" 上述程序执行时,会产生以下结果: Hello, Ruby! Ruby的多行注释 可以注释掉多行使用 =begin 和 =end 语法如下: #!/usr/bin/ruby -w puts "Hello, Ruby!" =begin This is

  • 详解Ruby语言中的注释用法与中文编码问题

    Ruby 注释 注释会对 Ruby 解释器隐藏一行,或者一行的一部分,或者若干行.您可以在行首使用字符( # ): # 我是注释,请忽略我. 或者,注释可以跟着语句或表达式的同一行的后面: name = "Madisetti" # 这也是注释 您可以注释多行,如下所示: # 这是注释. # 这也是注释. # 这也是注释. # 这还是注释. 下面是另一种形式.这种块注释会对解释器隐藏 =begin/=end 之间的行: =begin 这是注释. 这也是注释. 这也是注释. 这还是注释.

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

    写出自解释文档代码,然后让这部分歇息吧.这不是说着玩.     使用英文编写注释.     使用一个空格将注释与符号隔开.     注释超过一个单词了,应句首大写并使用标点符号.句号后使用 一个空格 避免多余的注释. # bad counter += 1 # increments counter by one 随时更新注释,没有注释比过期的注释更好. 不要为糟糕的代码写注释.重构它们,使它们能够"自解释".(Do or do not - there is no try.) 注解应该写在

  • 【经验总结】编写JavaScript代码时应遵循的14条规律

    本文讲述了编写JavaScript代码时应遵循的14条规律.分享给大家供大家参考,具体如下: 1. 总是使用 'var' 在javascript中,变量不是全局范围的就是函数范围的,使用"var"关键词将是保持变量简洁明了的关键.当声明一个或者是全局或者是函数级(function-level)的变量,需总是前置"var"关键词,下面的例子将强调不这样做潜在的问题. 不使用 Var 造成的问题 var i=0; // This is good - creates a

  • Xcode中代码注释编写的一些小技巧

    Xcode中代码注释编写的一些小技巧

    目录 前言 Objective-C的代码注释 Swift的代码注释 Objective-C和Swift的注释风格现在已经统一 快速修改注释 参考文档 总结 前言 码农总是在搬砖,日复一日,年复一年,有的时候都会麻木. 代码大家都会写,但是把注释写好却是一个技术活. 下面这段话,很好的说明了写好注释的感觉: 注释代码很像清洁你的厕所--你不想干,但如果你做了,这绝对会给你和你的客人带来更愉悦的体验.-- Ryan Campbell 今天给大家聊的就是在Xcode中,代码注释编写小技巧. Objec

  • windows下安装ruby与rails时遇到的问题总结

    前言 最近因为工作的需要,准备安装ruby on rails,在网上搜了下,步骤都类似,但实际安装过程中却碰到很多问题. 说明下:文章是按照我尝试的过程描述的.但最终是靠 运行 railsinstaller一键式安装包才成功的(第五段),因此前面的部分大家可以看看,但不用去尝试. 下面来看看详细的介绍吧: 一.首先要安装ruby 因为在windows下安装ruby,都是推荐下载rubyinstaller安装程序. 先进入ruby官网http://www.ruby-lang.org/en/down

  • PHP Document 代码注释规范

    1. 什么是phpDocumentor ? PHPDocumentor 是一个用PHP写的工具,对于有规范注释的php程序,它能够快速生成具有相互参照,索引等功能的API文档.老的版本是 phpdoc,从1.3.0开始,更名为phpDocumentor,新的版本加上了对php5语法的支持,同时,可以通过在客户端浏览器上操作生成文档,文档可以转换为PDF,HTML,CHM几种形式,非常的方便. PHPDocumentor工作时,会扫描指定目录下面的php源代码,扫描其中的关键字,截取需要分析的注释

  • 如何在JavaScript中谨慎使用代码注释

    前言 最令程序员头痛的事情莫过于阅读别人的代码,但其实时间一久阅读自己的代码也会很痛苦. 问题不是出在『自己或别人』,而是在代码本身. 必要的注释可以阐明实现细节和设计意图,以此节约自己和别人的时间. 然而很多时候注释起的作用却适得其反,比如自动生成的过多的注释分散阅读者的注意力, 而过期的失效的注释更是误导阅读者. 自动生成的注释 代码注释的泛滥想必是从Eclipse,Visual Studio等IDE开始的. 这些IDE提供了很多快捷功能,生成类/接口的骨架,具有Getter/Setter的

  • Python代码注释规范代码实例解析

    一.代码注释介绍 注释就是对代码的解释和说明,其目的是让人们能够更加轻松地了解代码. 注释是编写程序时,写程序的人给一个语句.程序段.函数等的解释或提示,能提高程序代码的可读性. 在有处理逻辑的代码中,源程序有效注释量必须在20%以上. 二.代码注释分类 行注释:在符号后那一行不会被编译(显示) 块注释:被块注释符号中间的部分不会被编译 三.python代码注释基础 Python中使用#表示单行注释.单行注释可以作为单独的一行放在被注释代码行之上,也可以放在语句或表达式之后.如下例子: name

  • Java代码注释规范详解

    Java代码注释规范详解

    代码附有注释对程序开发者来说非常重要,随着技术的发展,在项目开发过程中,必须要求程序员写好代码注释,这样有利于代码后续的编写和使用. 基本的要求: 1.注释形式统一 在整个应用程序中,使用具有一致的标点和结构的样式来构造注释.如果在其它项目中发现它们的注释规范与这份文档不同,按照这份规范写代码,不要试图在既成的规范系统中引入新的规范. 2.注释内容准确简洁 内容要简单.明了.含义准确,防止注释的多义性,错误的注释不但无益反而有害. 3.基本注释(必须加) (a) 类(接口)的注释 (b) 构造函

  • Ruby中使用SWIG编写ruby扩展模块实例

    在使用ruby/rails的过程中,确实发现有时性能不尽人意,如生成一个拥有600项的item的3层树形结构目录要花去20ms,为提高性能在学习用c/c++写ruby模块的过程中,认识了swig,rubyInline等一系列帮助编写c/c++来提升ruby性能的辅助工具. rubyInline用于内嵌c/c++程序,简单快捷,swig则帮助我们更容易地用c/c++写出独立的ruby模块. swig的入门使用方法 目标:用swig/c++编写一个ruby模块Test,并提供add方法作加法运算.

  • Android Studio 配置:自定义头部代码注释及添加模版方式

    1. 自定义头文件注释: 实现效果 实现步骤 依次操作File -> Settings ->Editor ->File and Code Templates,在详细展示窗口点击includes选项卡,找到 FileHeader点击,在编辑窗口输入自定义的注释模板即可.如下图: 注:我们这里添加的头文件不会随着Activity的创建自动添加头文件,只有创建JavaBean时会自动添加头文件,如下图所示: 2. 如何给Activity添加头文件?? 依次操作File -> Settin

随机推荐