前言
有一些人认为,好的代码是自我解释的。合适的命名和优秀的代码的确可以减轻开发人员阅读代码的工作量,对于不是特别复杂的代码可能确实可以做到自我解释。但并不是所有场景都可以做到这一点,我们一起来了解一下“注释”吧。
注释就是对代码的解释和说明。注释是开发人员在编写程序时,给一段代码的解释或提示,有助于提高程序代码的可读性。注释不会被计算机编译。
注释的存在就是为了方便自己的二次阅读和代码维护以及项目交接。可以更好的理解代码,有助于提高协作效率,加快开发进程。
试想,你添加了一段逻辑较为复杂的代码,几个月后再看,还能不能迅速看懂?你刚刚接手一个老项目,项目里基本没有注释且逻辑复杂,你能高效率的看懂代码和了解业务吗?
所以添加注释还是有一定必要滴。
“快捷键 windows:
ctrl+/
mac:command+/
一、 HTML 中的注释
<div>
这是一行文字
<!-- 这是一行被注释的文字 -->
</div>
二、CSS 中的注释
<style>
div {
/* color: #fff; */
}
</style>
div {
/* color: #fff; */
}
div {
/* color: #fff;*/ /* 多行注释*/
// font-size: 14px; // 单行注释
background: #000;
}
三、JS 中的注释
//
开头。任何位于 //
之后的文本都会被注释// 定义一个空数组
var ary = [];
var ary2 = []; // 又定义一个空数组
/*
开头,以 */
结尾。任何位于 /*
和 */
之间的文本都会被注释/*
这是多行注释
定义一个数组
*/
var ary = [];
//alert("123") // 执行时未弹出该信息
alert("456") // 执行时弹出该信息
/**
开头,以 */
结尾。任何位于 /**
和 */
之间的文本都会被注释/**
* 提交
*
* @method onSubmit
* @param {[Object]} 提交数据
* @return {[Bollean]} [返回是否提交成功 ]
*/
const onSubmit = (params = {}) => {
const result = false;
if (params) {
result = true;
}
return result;
};
四、特殊标记注释
// TODO功能未完成,待完善
// FIXME 待修复
// XXX 实现方法待确认
// NOTE 代码功能说明
// HACK 此处写法有待优化
// BUG 此处有 Bug
const arr = []
Tips:
//
注释可以在 .less 或 .scss 文件中使用,但是在 .html 和 .css 文件中不生效?/* */
一种语法。但是在 LESS 和 SCSS 中支持注释的语法和 JS 中保持一致,有单行注释 //
和多行注释 /* */
两种。单行注释编译之后不会被保留。 /*
* 简述当前文件功能
* @author 作者名称
* @version 版本号 最近编辑时间
* @description 该版本改动信息
*/
//
后留一个空格 // 这是一行注释
/*
这里有一行注释
这里有一行注释
这里有一行注释
*/
*
开头,且与第一行第一个 *
对齐*
间留一个空格/**
* 方法说明
* @method 方法名
* @for 所属类名
* @param {参数类型} 参数名 参数说明
* @return {返回值类型} 返回值说明
*/
*
表示任何类型?
表示可以为 null
!
表示不能为 null
[]
表示数组/**
* @type {number}
*/
var foo1;
/**
* @type {*}
* @desc 任何类型
*/
var foo2;
/**
* @type {?string}
* @desc string或者null
*/
var foo3;
[]
=
表示@param
对其属性进行详细说明...
表示/**
* @func
* @desc 一个带参数的函数
* @param {string} a - 参数a
* @param {number} b=1 - 参数b默认值为1
* @param {string} c=1 - 参数c有两种支持的取值 1—表示x 2—表示xx
* @param {object} d - 参数d为一个对象
* @param {string} d.e - 参数d的e属性
* @param {object[]} g - 参数g为一个对象数组
* @param {string} g.h - 参数g数组中一项的h属性
* @param {string} [j] - 参数j是一个可选参数
*/
function foo(a, b, c, d, g, j) {}
/**
* @func
* @desc 一个带若干参数的函数
* @param {...string} a - 参数a
*/
function bar(a) {}
了解更多可查看 JSDoc: http://yuri4ever.github.io/jsdoc/
IE 条件注释分为以下几种情况:
<!--[if IE]><![endif]-->
<!--[if IE 7]><![endif]-->
<!--[if !IE 7]><![endif]-->
<!--[if gt IE 7]><![endif]-->
<head>
<title>IE 条件注释</title>
<!-- 是 IE 时 -->
<!--[if IE]>
<link href="style.css" rel="stylesheet" type="text/css" />
<![endif]-->
<!-- 是 IE 7 时 -->
<!--[if IE 7]>
<link href="style.css" rel="stylesheet" type="text/css" />
<![endif]-->
<!-- 不是 IE 7 时 -->
<!--[if !IE 7]>
<link href="style.css" rel="stylesheet" type="text/css" />
<![endif]-->
<!-- 大于 IE 7 时 -->
<!--[if gt IE 7]>
<link href="style.css" rel="stylesheet" type="text/css" />
<![endif]-->
<!-- 小于 IE 7 时 -->
<!--[if lt IE 7]>
<link href="style.css" rel="stylesheet" type="text/css" />
<![endif]-->
</head>
#
一般出现在各种脚本配置文件中,用法与 JS 单行注释 //
基本相同。Python 中也常常用到'''
是 Python 中的多行注释语法,用两个 '''
包含被注释的段落# python 的单行注释一
print("I could have code like this.") # python 的单行注释二
# print("This won't run.") # 被注释的代码
'''
被三引号包裹的段落
可以随意折行
也可以注释代码
print("This won't run.")
'''
众所周知,注释的代码是不会被执行的。但是小编在查资料时看到了一段比较有意思的代码, Java 中的一行注释“被执行”了?
public class Test {
public static void main(String[] args) {
String name = "赵大";
// \u000dname="钱二";
System.out.println(name);
}
}
这段代码执行后的结果为钱二
,也就是说在这段代码中,“被注释”的那行代码生效了!
这段代码的问题出在 \u000d
这串特殊字符上。\u000d
是一串 Unicode 字符,代表换行符。Java 编译器不仅会编译代码,还会解析 Unicode 字符。在上面这段代码把 \u000d
给解析了,后面的代码就到了下面一行,超出了被注释的范围(单行注释的注释范围仅在当前行),所以执行结果为 钱二
而非 赵大
。(如下)
public class Test {
public static void main(String[] args) {
String name = "赵大";
//
name="钱二";
System.out.println(name);
}
}
所以本质上在代码执行的时候 name="钱二"
并没有被注释,而是被换了行(奇怪的知识增加了)。所以切记,注释确实是不会被执行的哦!
在这里推荐几个个人认为比较好用的注释相关的 Vscode 插件,可在 setting.json
文件下自定义设置(可通过 '文件—首选项—设置',打开 Vscode 文件 settings.json
)
window
:ctrl+alt+i
,mac
:ctrl+cmd+i
,linux
:ctrl+meta+i
window
:ctrl+alt+t
,mac
:ctrl+cmd+t
,linux
:ctrl+meta+t
口说无凭,眼见为实。下面我们看下实际开发中的具体情况:
const noWarehousetemIds = beSelectSkucontainer.reduce((arr, itemId) => {
const res = Object.keys(selectRowskey[itemId]).every((skuId) => {
const sku = selectRowskey[itemId][skuId];
return !!sku.warehouseCode || lodashGet(warehouses, '[0].code');
});
if (!res) {
arr.push(itemId);
}
return arr;
}, []);
if (noWarehousetemIds.length > 0 || noStockItemIds.length > 0) {
const itemIds = Array.from(new Set([...noWarehousetemIds, ...noStockItemIds]));
const itemNames = itemIds.map(i => this.itemNameMap[i].itemName);
return Modal.warning({
title: '错误提示',
content: `“${itemNames.join(',')}”库存信息未完善,请完善库存信息`,
});
}
// 遍历当前所有选中的sku,查找出没有库存的itemId
const noStockItemIds = beSelectSkucontainer.reduce((arr, itemId) => {
const res = Object.keys(selectRowskey[itemId]).every((skuId) => {
const sku = selectRowskey[itemId][skuId];
return !!sku.stockQuantity;
});
if (!res) {
arr.push(itemId);
}
return arr;
}, []);
// 有一条sku的库存为空时进入校验
if (noStockItemIds.length > 0) {
const itemNames = itemIds.map(i => this.itemNameMap[i].itemName);
return Modal.warning({
title: '错误提示',
content: `“${itemNames.join(',')}”库存信息未完善,请完善库存信息`,
});
}
// 遍历当前所有选中的sku,查找出没有库存的itemId
const noStockItemIds = beSelectSkucontainer.reduce((arr, itemId) => {
// selectRowskey是一个对象,以itemId为key,sku对象作为value,sku对象以skuId作为key,sku作为value,只有selectRowskey下所有itemId下的sku都有库存才算校验通过
/*
数据格式:
selectRowskey: {
12345678: { // itemId
123456: { // skuId
name: 'sku',
}
}
}
*/
const res = Object.keys(selectRowskey[itemId]).every((skuId) => {
const sku = selectRowskey[itemId][skuId];
return !!sku.stockQuantity;
});
// 只要有一条sku没有库存时,就塞到arr中,返回给noStockItemIds数组
if (!res) {
arr.push(itemId);
}
return arr;
}, []);
// 有一条sku的库存为空时进入校验
if (noStockItemIds.length > 0) {
// 根据id查找商品名称
const itemNames = itemIds.map(i => this.itemNameMap[i].itemName);
Modal.warning({
title: '错误提示',
content: `“${itemNames.join(',')}”库存信息未完善,请完善库存信息`,
});
}
看到上面这段代码可以很明显的体会到有没有注释以及注释写的清不清楚的重要性。若是写了注释但仍然看不懂,那还不如不写。
所以注释也不是随便写一写就可以的,要描述某段代码的功能,注明逻辑,让开发者可以”无脑“浏览。
之前在工作群中看到有人发过这样一张图(如下图),个人认为是一个很好的代码注释的范例:
看到这里,对于注释的重要性各位已经有自己的认知。还有几点是我们写注释时需要注意的:
为什么要写注释: https://www.cnblogs.com/jinhongquan/p/12084984.html
js/javascript代码注释规范与示例: https://www.cnblogs.com/chris-oil/p/4067415.html
代码中的特殊注解 -- TODO、FIXME、XXX的作用: https://blog.csdn.net/dietime1943/article/details/53466749
注释的作用, 以及如何写注释: https://www.cnblogs.com/fzd19zx/archive/2013/06/06/3120811.html
你确定Java注释不会被执行吗?80%的人都不知道: https://www.cnblogs.com/chengxuyuanaa/p/12838284.html
IE 浏览器条件注释详解: https://blog.csdn.net/hdchangchang/article/details/8199054
关于CSS中对IE条件注释的问题: https://zhidao.baidu.com/question/262696188.html
扫码关注腾讯云开发者
领取腾讯云代金券
Copyright © 2013 - 2025 Tencent Cloud. All Rights Reserved. 腾讯云 版权所有
深圳市腾讯计算机系统有限公司 ICP备案/许可证号:粤B2-20090059 深公网安备号 44030502008569
腾讯云计算(北京)有限责任公司 京ICP证150476号 | 京ICP备11018762号 | 京公网安备号11010802020287
Copyright © 2013 - 2025 Tencent Cloud.
All Rights Reserved. 腾讯云 版权所有