• 《编写可维护的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
    本文版权归作者和博客园共有,欢迎转载,但未经作者同意必须保留此段声明,且在文章页面明显位置给出原文连接。谢谢合作。

    -->

  • 相关阅读:
    vue 组件开发 props 验证
    vue中$emit与$on
    vue中的 ref 和 $refs
    Animate.css动画特效
    Css Tada动画效果(Css Tada Animation Effect)--- shake抖动效果
    给某个dom对象添加动画fadeIn、fadeInDown、flipInY、jackInTheBox
    uniapp导航栏自定义按钮及点击事件
    uniapp的微信小程序,获取授权,获取中文街道地理位置
    在mac上如何用safari调试ios手机的移动端页面
    条件编译
  • 原文地址:https://www.cnblogs.com/beginner2014/p/5408884.html
Copyright © 2020-2023  润新知