JavaScript如何正确的写代码注释

更新时间：2023年10月07日 15:35:50 作者：坚毅的小解同志

这篇文章主要给大家介绍了关于JavaScript如何正确的写代码注释的相关资料,注释的作用是提高代码的可读性,帮助自己和别人阅读和理解你所编写的JavaScript代码,注释的内容不会在网页中显示,需要的朋友可以参考下

错误注释

你的注释是不是这样的？

//时间戳日期格式化函数
function formTime(time,isyear){   
}

亦或者是这样的？

/*
时间戳日期格式化函数
 */ 
function formTime(time,isyear){
}

简单的变量声明之类的内容可以进行简单注释，但是函数就不能这样做了，要知道注释的作用是一种为了让代码更易读、易维护、易理解，起到提示的作用的，上面的两个注释都是正确的，但是它起到的作用太低了，在正式工作中我们往往会协同开发，这种注释是万万不可的。

正确注释

正确的注释就是文档注释，先来看看是什么样子。

 /**
    * @author 小解同志  https://lamian.blog.csdn.net
    * @param {String} time  接受用户传来的时间戳
    * @param {Boolean} isyear  是否要显示年月日
    * @example formTime('3434322332',true)  格式化时间戳并显示年月日
    */
   function formTime(time,isyear){
   }

是不是比之前的注释多了很多，内容详细了很多，当然，不只是单单的内容多了，如果只是内容多了那么/* */段落注释同样也可以写，那么它还有什么优点呢？

优点

方法提示

time是个字符串我们要截取字符串

普通注释

文档注释

内容提示

鼠标移动到函数以及参数上所给的提示。

普通注释

文档注释

这种提示就像嵌代码在里面一样，而不是浮于表面了，在我们书写npm包的时候，用户使用我们的包，就能看到这种提示，对使用者特别友好。

自动化生成文档

既然叫文档注释，那么生成个文档也没什么好奇怪的吧，生成文档的包有很多种，比如jsDoc，apiDoc等等，在这里我使用jsdoc。

安装

输入以下命令进行全局安装。

npm install jsdoc -g

基本使用

jsdoc 文件名其他的使用方式可以去官网查看

jsdoc 33.js

执行完此命令，会生成一个out文件夹，查看里面的index页面即可，右边侧边栏会显示函数的使用

总结

到此这篇关于JavaScript如何正确的写代码注释的文章就介绍到这了,更多相关js正确写代码注释内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

三种方式获取XMLHttpRequest对象
这篇文章主要介绍了获取XMLHttpRequest对象的三种方式,需要的朋友可以参考下
2014-04-04
微信小程序实现tab组件切换动画
tab相对而言用的还是比较多的,但是用起来并没有难,下面这篇文章主要给大家介绍了关于微信小程序全局配置之tab的相关资料,文中通过图文以及示例代码介绍的非常详细,需要的朋友可以参考下
2022-10-10
浅析JavaScript中的隐式类型转换
这篇文章主要是对JavaScript中的隐式类型转换进行了详细分析介绍，需要的朋友可以过来参考下，希望对大家有所帮助
2013-12-12
在JavaScript中模拟类(class)及类的继承关系
众所周知,JavaScript中没有类,然而我们却可以动手实现一个拥有继承特性的类,所以接下来我们要讨论的便是在JavaScript中模拟类(class)及类的继承关系:
2016-05-05
总结在前端排序中遇到的问题
这篇文章给大家罗列了在前段排序中会遇到的问题并写了解决方案，非常详细，有需要的朋友可以参考。
2016-07-07
彻底搞懂JS中call、apply、bind的区别与应用
在JavaScript中函数执行时的this值默认由调用方式决定,但可通过call、apply和bind方法显式控制,这三种方法的核心功能均为修改this指向,但在执行时机、参数传递和返回值上存在差异,这篇文章主要介绍了JS中call、apply、bind区别与应用的相关资料,需要的朋友可以参考下
2026-04-04
Bootstrap警告（Alerts）的实现方法
这篇文章主要为大家详细介绍了Bootstrap警告（Alerts）的实现方法，具有一定的参考价值，感兴趣的小伙伴们可以参考一下
2017-03-03
javascript常用经典算法详解
本文主要介绍了javascript七种常见算法：冒泡排序；插入排序；希尔排序；归并排序；快速排序；选择排序；奇偶排序。具有一定的参考价值，下面跟着小编一起来看下吧
2017-01-01
js微信应用场景之微信音乐相册案例分享
这篇文章主要为大家分享了js微信应用场景之微信音乐相册案例，具有一定的参考价值，感兴趣的小伙伴们可以参考一下
2017-08-08
JS获取input file绝对路径的方法(推荐)
下面小编就为大家带来一篇JS获取input file绝对路径的方法(推荐)。小编觉得挺不错的，现在就分享给大家，也给大家做个参考。一起跟随小编过来看看吧
2016-08-08