二、注释

2.1 单行注释

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

单行注释有三种写法:

(1)独占一行的注释,用来解释下一行代码。这行注释之前总是有一个空行,且缩进层级和下一行保持一致。

(2)在代码行的尾部的注释。代码结束到注释之间至少有一个缩进。注释(包括之前的代码部分)不应当超过单行最大字符数限制,如果超过了,就将这条注释放置于当前代码行的上方。

(3)被注释掉的大段代码(很多编辑器都可以批量注释掉多行代码)。

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

// 好的写法
if (condition) {

    // 如果代码执行到这里,则表明通过了所有安全性检查
    doSomething();
}

// 不好的写法:注释之前没有空行
if (condition) {
    // 如果代码执行到这里,则表明通过了所有安全性检查
    doSomething();
}

// 不好的写法:错误的缩进
if (condition) {
// 如果代码执行到这里,则表明通过了所有安全性检查
    doSomething();
}

// 好的写法
var result = something + somethingElse; //somethingElse不应当取值为null

// 不好的写法:代码和注释之间没有间隔
var result = something + somethingElse;//somethingElse不应当取值为null

// 好的写法
// if (condition) {
//     doSomething();
// }

// 不好的写法:这里应当用多行注释
// 接下来的这段代码非常难,那么,我来详细解释一下
// 这段代码的作用是首先判断条件是否为真
// 只有当为真时才会执行
// 多个函数计算出来的,在整个会话生命周期内
// 这个值是可以修改的
if (condition) {
    // 如果代码执行到这里,则表明通过了所有安全性检查
    doSomething();
}

2.2 多行注释

多行注释可以包裹跨行文本。它以/*开始,以*/结束。

Java风格的注释至少包含三行:第一行是/*,第二行是以*开始且和上一行的*保持左对齐,最后一行是*/。

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

// 好的写法
if (condition) {

    /*
     * 如果这行代码执行到这里
     * 说明通过了所有安全性检测
     */
    doSomething();
}

// 不好的写法:注释之前没有空行
if (condition) {
    /*
     * 如果这行代码执行到这里
     * 说明通过了所有安全性检测
     */
    doSomething();
}

// 不好的写法:星号后面没有空格
if (condition) {

    /*
     *如果这行代码执行到这里
     *说明通过了所有安全性检测
     */
    doSomething();
}

// 不好的写法:错误的缩进
if (condition) {

  /*
   *如果这行代码执行到这里
   *说明通过了所有安全性检测
   */
    doSomething();
}

// 不好的写法:代码尾部注释不要用多行注释风格
var result = something + somethingElse; /*somethingElse不应当取值为null*/

2.3 使用注释

一种通行的指导原则是,当代码不够清晰时添加注释,而当代码很明了时不应当添加注释。比如下面的例子,注释是画蛇添足。

// 初始化count

var count = 10;

因为代码中初始化count的操作是显而易见的。注释并没有提供其他有价值的信息。换个角度讲,如果这个值10具有一些特殊的含义,而且无法直接从代码中看出来,就没有必要添加注释了。

// 改变这个值可能会让它变成青蛙

var count = 10;

如果没有添加注释,你修改了count的值,变成了青蛙,就会让人困惑不解。

因此,添加注释的一个原则是,在需要让代码变得更清晰时添加注释。

2.3.1 难于理解的代码

难于理解的代码通常都应当加注释。根据代码的用途,你可以进行单行注释,多行注释,或者混合使用这两种注释。关键是让其他人更容易读懂这段代码。

2.3.2 可能被误认为错误的代码

另一个适合添加注释的好时机是当代码看上去有错误时。在团队开发中,总是会有好心的开发者在编辑代码时发现他人的错误代码,就立即将它修复。有时这段代码并不是错误的源头,所以“修复”这个错误往往会制造其他错误,因为本次修改应当是可追踪的。当你写的代码有可能会被别的开发者认为有错误时,则需要添加注释。

2.3.3 浏览器特性hack

JavaScript程序员常常会编写一些低效的、不雅的、彻头彻尾的肮脏代码,用来让低级浏览器正常工作。实际上这种情形是一种特殊的“可能被误认为是错误的代码”:这种不明显的做浏览器特性Hack的代码可能隐含一些错误。

2.4 文档注释

JavaDoc文档格式:多行注释以单斜线加双星号(/**)开始,接下来是描述信息,其中使用@符号来表示一个或多个属性。

/**
 * 这是一个计算整数和的方法
 * @method addNumber
 * @param {Number} 整数
 * @return {Number} 一个计算后的结果
 */
 var addNumber = function (x, y) {
     return x + y;
 }

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

(1)所有的方法

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

(2)所有的构造函数

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

(3)所有包含文档化方法的对象

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

当然,注释的格式和用法最终还是由你所选择的文档生成工具决定的。

时间: 2024-10-12 23:21:51

二、注释的相关文章

javascript的注释

编写代码的时候,可能会给代码添加一定的说明,以提高代码的可读性.注释内容并不会被当做代码执行,所以需要一定的规范和格式.一.注释单行代码:格式是: //注释的内容 例如: <script type="text/javascript">  var a=1,b=2  var c;  c=a+b;  alert(c);  //将c输出  document.write(c); </script> 注:此种格式只能够一次注释一行内容.二.注释多行代码:格式是: /* 注释

更精简的代码,更详细的注释,让项目更容易维护

更精简的代码,更详细的注释,让项目更容易维护,因为项目的本质不是代码,是算法,是实现步骤, 如果代码不精简,很臃肿,时间久了,具体实现过程会记忆模糊的,代码臃肿,以后是要花费更多时间读的. 有时可以在写的时候,就一边小重构一下,不要等到以后再重构 一精简重构的一些方式: 1抽取方法:抽取常用的功能,可以放到一些综合工具类里 2抽取变量:尤其是对于要用到很多if-else结构里的变量,可以先定义一个空变量,然后根据不同的情况, 进行赋值. 3砍掉变量:一个复杂系统肯定有很多的对象和变量,其实仔细思

C/C++ 代码规范: 命名规则、注释、格式

摘抄精简Google 开源项目风格指南: http://zh-google-styleguide.readthedocs.org/en/latest/contents/ 一. 命名规则 永远不要使用单词缩写(如count写成cnt) 变量名: 小写字母,下划线连接,一般用名词,如error_count 类的成员变量以下划线结尾,如my_exciting_member_variable_ 结构体的数据变量,小写字母,下划线连接 全局变量,前缀g_ ,如g_global_variable 常量: 加

一个SQL注释引发的线上问题

最近开始服务拆分,时间将近半个月.测试阶段也非常顺利,没有什么问题. 但上线之后的第二天,产品就风风火火的来找我们了,一看就是线上有什么问题.我们也不敢说,我们也不敢问,线上的后台商品忽然无法上架了,导致运营的同学删除商品后无法上架新的商品,导致APP的部分商品暂时不可见. 线上有问题,那么大家就开始迅速排查起来了.这里有一点要说一下,在上线前夕,产品临时添加一个新的需求,商品的搜索状态不可判断这个条件去掉,这个由于紧急而且对于我们来说也就是SQL中的一个条件的问题,也就没有经过测试,直接上线了

注释和变量

一. 第一个Python程序 1 print("hello python") 二. 注释 1 # 单行注释 2 3 """ 4 多行注释 5 """ 6 # 官方推荐 三个双引号 1. 代码注释原则 1>. 不用给全部代码加注释,只需要在自己觉得重要或不好理解的部分加注释即可. 2>. 注释可以用中文或英文,但绝对不要拼音. 3>. 注释不光要给自己看,还要给别人看,所以请认真写. 三. 变量 1. 变量,是

第3篇-JAVA基础

第3篇-JAVA基础 每篇一句 :目标是给梦想一个期限,行动与坚持就是实现梦想的过程 初学心得: 遇到困难或问题,它不是休止符,而是引向你如何解决问题的标识 (笔者:JEEP/711)[JAVA笔记 | 时间:2017-03-26| JAVA基础 Ⅱ] 上篇回顾 上篇文章中我们学习了JAVA底层的运行机制与深入剖析以及解释其中JAVA基础代码的含义 本篇文章将JAVA基础Ⅱ全面剖析解释,因为JAVA基础非常重要,务必要牢记知识点!!! 1.JAVA基础语法格式 JAVA采用unicode编码 1

Linux常用的基本命令12

sort作用:将文本排序显示常用选项:    -u 去除重复行    -r 降序(默认升序)    -n 以数值来排序    -t 指定分隔符        -k n以第n列来排序实例: [[email protected] ~]# cat hi  a:2 b:3 b:1 b:1 c:4 d:5 [[email protected] ~]# sort -u hi  a:2 b:1 b:3 c:4 d:5 [[email protected] ~]# sort -r hi  d:5 c:4 b:3

Web前端开发规范手册

一.规范目的 1.1 概述 ..................................................................................................................................... 1 二.文件规范 2.1 文件命名规则...................................................................................

[转] 常用的CSS命名规则

(一)常用的CSS命名规则  头:header  内容:content/container  尾:footer  导航:nav  侧栏:sidebar  栏目:column  页面外围控制整体布局宽度:wrapper  左右中:left right center  登录条:loginbar  标志:logo  广告:banner  页面主体:main  热点:hot  新闻:news  下载:download  子导航:subnav  菜单:menu  子菜单:submenu  搜索:searc

css模块化思想(一)--------命名是个技术活【转】

正篇: 什么是css模块化思想?(what) 为了理解css模块化思想,我们首先了解下,什么是模块化,在百度百科上的解释是,在系统的结构中,模块是可组合.分解和更换的单元.模块化是一种处理复杂系统分解成为更好的可管理模块的方式.它可以通过在不同组件设定不同的功能,把一个问题分解成多个小的独立.互相作用的组件,来处理复杂.大型的软件.看完模块化,是不是有种拼图的即视感,可以把大图分成各个小图,然后把小图拼成大图,分与合的艺术感.那么css模块化思想,也就是在css编写环境中,用上模块化的思想,把一