前言有些人认为好的代码是不言自明的。恰当的命名和好的代码确实可以减少开发人员阅读代码的工作量，而且对于不是特别复杂的代码，确实可能是不言自明的。但并不是所有的场景都能做到这一点，我们来看看“注意事项”。编程语言中对“注释”的解释注释是对代码的解释和说明。注释是开发人员在编写程序时对一段代码的解释或提示，有助于提高程序代码的可读性。评论不是计算机编译的。你想添加评论吗？为什么要添加注解？注释的存在是为了方便自己的二次阅读、代码维护和项目交接。您可以更好地理解代码，有助于提高协作效率，加快开发进程。试想，如果你加入一段逻辑比较复杂的代码，几个月后再看，你还能很快看懂吗？你刚刚接手了一个旧项目。项目中基本没有注释和复杂的逻辑。能看懂代码，高效理解业务吗？所以还是有必要补充一下。基本快捷键Windows系统：Ctrl+/ios系统：Command+/HTML中的注释分类
这是一行文字
CSS中的注释div{/*color:#fff;*/}div{/*color:#fff;*//*多行注释*///font-size:14px;//单行注释background:#000;}在HTML中，在.css文件中，在.less或.scss文件中，JS中注释的使用可以用来解释JavaScript代码，增强其可读性。也可用于防止代码执行。单行注释（linecomments）——以//开头。//之后的任何文本都将被注释多行注释（块注释）-以/*开头并以*/结尾。/*和*/之间的任何文本都会被注释掉/*Thisisamulti-linecommentdefinedanarray*/varary=[];*使用注释来防止代码执行——被注释的JS代码不会被执行```js//alert("123")//执行时不弹出消息alert("456")//执行时弹出消息```函数注释一般以/**开头，以*/结尾。/**和*/之间的任何文本都会被注释掉/***submit**@methodonSubmit*@param{[Object]}submitdata*@return{[Bollean]}[返回是否提交成功]*/constonSubmit=(params={})=>{constresult=false;if(params){result=true;}returnresult;};特别标记commentTODO该注释处有功能代码要写，要实现的功能在描述中会简单说明注释处FIXME的代码需要更正，即使代码错误，也不能工作,需要维修。如何修复会在说明中简单说明，虽然注释处XXX的代码已经实现了功能，但实现方法有待商榷。我希望它能在未来得到改进。需要改进的地方将在说明书中简单说明。注意在这个注释中解释代码是如何工作的。HACK在此说明中编写或格式化不当。您需要根据需要调整程序代码。BUG在这个note这里有bug//TODO功能未完成，有待改进//FIXME待修复//XXX实现方法待确认//NOTE代码功能说明//HACK这里待优化//这里的BUG是Bugconstarr=[]Tips：为什么//注释在.less或.scss文件中起作用，而在.html和.css文件中不起作用？MDN上的CSS注释只有/**/语法。但是LESS和SCSS支持注释的语法和js是一致的。有单行注释//和多行注释/**/两种。编译后不保留单行注释。为什么单行注释有时写在代码上面，有时写在代码后面？注释可以放在代码的任何地方。个人理解，一般写在代码上面就是对后面一段代码的注释，写在代码后面就是对当前行代码的注释。注释书写规范文件注释位于文件头部，一般包括摘要、作者、版本变更信息、修改时间等。/**当前文件功能简要说明*@authorauthorname*@version版本号上次编辑时间*@description本版本变更信息*/单行注释后始终留一个空格////这是单行注释多行注释始终保持星号垂直对齐（结束前留一个空格character)不要在开始和结束字符所在的行写注释当尝试使用单行注释而不是多行注释来注释函数时，建议使用多行注释/*这里是一行ofcommentsHereisalineofcommentsHereisalineofcomments*/每行函数注释以*开头，第一行第一行每行*对齐注释的内容之间要有一个空格，*必须包含l亚伯评论。例子：```javascript/**方法描述@method方法名@for所属类名@param{参数类型}参数名参数描述@return{返回值类型}返回值描述/注解常用标签用法@type{typeName}*表示任何类型？手段可以为空！表示不能为空[]表示数组```javascript/**@type{number}/varfoo1;/**@type{*}@desc任何类型/varfoo2;/**@type{?string}@descstringornull/varfoo3;*@param{
}name-somedescription*为非必填参数的参数名添加'[]'*如果参数有一个默认值用'='表示*如果参数是对象，可以继续用`@param`来详细描述它的属性*几个参数用`...`表示```javascript/***@func*@desconeFunctionwithparameters*@param{string}a-参数a*@param{number}b=1-参数b默认值为1*@param{string}c=1-参数c有两个支持的值1—代表x2—代表xx*@param{object}d-parameterd是一个object*@param{string}d.e-parametereparameterd*@param{object[]}g-parameter的属性g是一个对象数组*@param{string}g.h-参数g数组中某一项的h属性*@param{string}[j]-参数j是一个可选参数*/functionfoo(a,b,c,d,g,j){}/***@func*@desc具有多个参数的函数*@param{...string}a-parametera*/functionbar(a){}如需了解更多信息，请参考JSDocExpansionIECon??ditionalComments(IE5+)IE条件注释分为以下几种两种情况：只允许IE解释只允许IE特定版本解释只允许非IE特定版本执行注释只允许更高或更低的IE特定版本执行注释IE条件注释#（井号）注释和'''（三引号）注释#一般出现在各种脚本中在配置文件中，用法与JS单行注释基本相同//Python也经常使用'''是Python中的多行注释语法，使用''''''包含被注释的段落#Python单行注释-print("Icouldhavecodelikethis.")#Python的单行注释2print("Thiswon'trun.")#注释代码'''三引号包裹的段落可以随意包裹或者注释代码print("Thiswon'trun.'trun.")'''####注释“执行”？众所周知，注释掉的代码是不会被执行的。但是小编在查资料的时候看到了一段比较有意思的代码。Java的一行注释被“执行”了？```javapublicclassTest{publicstaticvoidmain(String[]args){Stringname="赵大";//\u000dname="钱二";System.out.println(name);}}这段代码执行的结果是钱二，也就是说，在这段代码中，“注释掉”的代码行生效了！这段代码的问题是特殊字符字符串\u000d。\u000d是表示换行符的Unicode字符串。Java编译器不仅编译代码，还解析Unicode字符。上面的代码中解析了\u000d，下面的代码到了下面一行，超出了注释的范围（单行注释的注释范围只在当前行），所以执行结果为qian尔代替赵大。（如下）publicclassTest{publicstaticvoidmain(String[]args){Stringname="赵大";//name="千二";System.out.println(name);}}所以本质上代码执行的时候，name="Qian2"没有注释，而是换行（补充了奇怪的知识）。所以记住，评论确实是不会执行的！注释相关的插件这里介绍几个我觉得比较好用的注释相关的Vscode插件，可以在setting.json文件下自定义（可以通过'File-Preferences-打开Vscode文件settings.jsonsettings')koroFileHeader是一个插件，用于在vscode中生成文件头注释和函数注释给文件头添加注释在文件开头添加注释，记录文件信息/文件参数/退出参数等。支持用户使用高度自定义评论选项，适应每个要求和评论。保存文件时，自动更新上次编辑时间和编辑器快捷键：window：ctrl+alt+i，mac：ctrl+cmd+i，linux：ctrl+meta+i在光标处添加功能注释，自动在cursor生成评论模板，支持用户高度自定义评论选项快捷键：window：ctrl+alt+t，mac：ctrl+cmd+t，linux：ctrl+meta+t快捷键不可用，可能被占用并且可以自定义默认参数BetterComments通过用警报、信息、TODO等注释来改进代码注释。使用此扩展，您将能够将评论分类为：警报查询TODO突出显示注释掉的代码也可以设置样式，以便代码不应该存在可自定义以指定其他所需的评论样式TODO突出显示TODO，FIXME突出显示突出显示内置关键字任何关键字，您可以通过自定义设置来覆盖外观，您还可以自定义关键字。用事实说话。下面看实际开发中的具体情况：无评论itemId][skuId];return!!sku.warehouseCode||lodashGet(warehouses,'[0].code');});if(!res){arr.push(itemId);}returnarr;},[]);if(noWarehousetemIds.length>0||noStockItemIds.length>0){constitemIds=Array.from(newSet([...noWarehousetemIds,...noStockItemIds]));constitemNames=itemIds.map(i=>this.itemNameMap[i].itemName);returnModal.warning({title:'错误提示',content:`“${itemNames.join(',')}”库存信息不完整，请完善库存信息`,});}Generalcomments//遍历所有当前选择的skus，找到没有库存的itemIdsconstnoStockItemIds=beSelectSkucontainer.reduce((arr,itemId)=>{constres=Object.keys(selectRowskey[itemId]).every((skuId)=>{constsku=selectRowskey[itemId][skuId];return!!sku.stockQuantity;});if(!res){arr.push(itemId);}returnarr;},[]);//当某个sku的库存为空时，进入验证if(noStockItemIds.length>0){constitemNames=itemIds.map(i=>this.itemNameMap[i].itemName);returnModal.warning({title:'错误提示',content:`“${itemNames.join(',')}”库存信息不完整，请完善库存信息`,});}更好的评论//遍历所有当前选择的skus，找到没有库存的itemIdsconstnoStockItemIds=beSelectSkucontainer.reduce((arr,itemId)=>{//selectRowskey是一个对象，itemId为key，sku对象为value，sku对象以skuId为key，sku为value，只有selectRowskey下itemId下的所有sku都有库存才能校验通过/*数据格式：selectRowskey:{12345678:{//itemId123456:{//skuIdname:'sku',}}}*/constres=Object.keys(selectRowskey[itemId]).every((skuId)=>{constsku=selectRowskey[itemId][skuId];return!!sku.stockQuantity;});//作为只要有sku缺货，就会塞进arr，返回到noStockItemIds数组if(!res){arr.push(itemId);}returnarr;},[]);//当有sku库存为空输入验证if(noStockItemIds.length>0){//根据id查找商品名称constitemNames=itemIds.map(i=>this.itemNameMap[i].itemName);Modal.warning({title:'错误提示',content:`"${itemNames.join(',')}"库存信息不完整，请完善库存信息`,});}看到上面的代码，就可以清楚的了解到是否有评论和评论写不明确的重要性如果写了笔记还是看不懂，还是不写为好。所以评论不是随便写的。需要描述某段代码的功能，标明逻辑，让开发者不用思考就可以浏览。之前在工作群里看到有人发过这样一张图（如下图）。我个人认为是代码注释的一个很好的例子：结论看到这里，你已经对注释的重要性有了自己的理解。写评论还有几点需要注意：评论的内容要简洁明了。注释只是简单的描述功能或者实现逻辑，没有必要在每一行代码中都添加注释。如果修改了代码，记得同步修改相应的注释。不要有过期评论，否则会适得其反
