zoukankan      html  css  js  c++  java
  • 《编写可维护的JavaScript》——JavaScript编码规范(四)

    注释

    单行注释

    单行注释以两个斜线开始,以行尾结束

    单行注释有三种使用方法:

    • 独占一行的注释,用来解释下一行代码。这行注释前总是有一个空行,且缩进层级和下一行代码保持一致。
    • 在行尾的注释。代码结束到注释之间至少有一个缩进。注释(包括之前的代码部分)不应当超过单行最大字符数限制。如果超过了,就将这条注释放置于当前代码行的上方。
    • 被注释掉的大段代码(很多编辑器都可以批量注释掉多行代码)。

    单行注释不应当以连续多行注释的形式出现,除非你注释掉一大段代码。只有当需要注释一段很长的文本时才使用多行注释

    多行注释

    多行注释可以包裹跨行文本。它以/*开始,以*/结束。多行注释不仅仅可以用来包裹跨行文本,这取决于你。

    推荐的是java风格的多行注释。java风格的注释至少包含三行:第一行是/*,第二行是以*开始且和上一行的*保持左对齐,最后一行是*/。这种注释看起来像下面这样。

    /*

    * 另一段注释

    * 这段注释包含两行文本

    */

    通过在注释左侧注上星号,会让注释更清晰。有一些IDE(比如eclipse)会自动为你插入这些星号。星号后应有空格

    多行注释总是出现在将要描述的代码段之前,注释和代码之间没有空行间隔。和单行注释一样,多行注释之前当有一个空行,且缩进层级和其要描述的代码保持一致。

    使用注释

    何时添加注释是程序员经常争论的一个话题。一种通行的指导原则是,当代码不够清晰时添加注释,而当代码很明了时不应当添加注释。

    难于理解的代码通常都应当加注释。

    可能被误认为错误的代码,需要添加注释

    文档注释

    从技术的角度来讲,文档注释并不是JavaScript的组成部分,但它们是一种普遍的实践。文档注释最流行的一种格式来源于JavaDoc文档格:多行注释以/**开始,接下来是描述信息,其中使用@符号来表示一个或多个属性。来看一段来自YUI的源码的例子。

    /**
    返回一个对象,这个对象包含被提供对象的所有属性。
    后一个对象的属性会覆盖前一个对象的属性。
    传入一个单独的对象,会创建一个它的浅拷贝(shallow copy)。
    @method merge
    @param {Object} 被合并的一个或多个对象
    @return {Object} 一个新的合并后的对象
    Y.merge = function(){
    
        //此处省略
    
        return result;
    };
    

    当使用文档注释时,你应当确保对如下内容添加注释。

    • 所有的方法

    应当对方法、期望的参数和可能的返回值添加注释描述

    • 所有的构造函数

    应当对自定义类型和期望的参数添加注释描述

    • 所有包含文档化方法的对象

    如果一个对象包含一个或多个附带文档注释的方法,那么这个对象也应当适当地针对文档生成工具添加文档注释。

    <!--

    作者:纤锐
    出处:http://www.cnblogs.com/beginner2014
    本文版权归作者和博客园共有,欢迎转载,但未经作者同意必须保留此段声明,且在文章页面明显位置给出原文连接。谢谢合作。

    -->

  • 相关阅读:
    hdu 1042 N!
    hdu 1002 A + B Problem II
    c++大数模板
    hdu 1004 Let the Balloon Rise
    hdu 4027 Can you answer these queries?
    poj 2823 Sliding Window
    hdu 3074 Multiply game
    hdu 1394 Minimum Inversion Number
    hdu 5199 Gunner
    九度oj 1521 二叉树的镜像
  • 原文地址:https://www.cnblogs.com/beginner2014/p/5408884.html
Copyright © 2011-2022 走看看