Javascript注释规范
最近查看代码,看其他人的代码确实很让人头疼,由于没有任何注释规范,导致代码里很少有注释,或者注释写的很简练,今天对于注释规范进行总结。
js注释规范基于jsdoc,写出的代码注释能够成功生成注释文档。
由于jsdoc的规范太多,为了项目的可用性,对jsdoc的某些属性进行提取形成文档,供开发人员使用。
方法注释
基本方法块注释
如果描述不能描述清楚,添加例子来描述。
/*** @method* @param {Type} data 目标对象* @returns {Type} 运营商名称* @desc 根据目标对象获取运营商*/
function matchedNumber(data){return '返回对象'
}
基本方法块注释,注释过长
/*** @method* @param {Type} data 目标对象<br/>* 例:* {* target:手机号* }* @returns {Type} 运营商名称* @desc 根据目标对象获取运营商*/
function matchedNumber(data){return '返回对象'
}
如果需要折行则在文本中使用<br/>
标签
基本方法块注释,参数可选
/*** @method* @param {Type} [data] 目标对象* 例:* {* target:手机号* }* @returns {Type} 运营商名称* @desc 根据目标对象获取运营商*/
function matchedNumber(data){return '返回对象'
}
基本方法块注释,带默认值
/*** @method* @param {Type} data={} 目标对象* 例:* {* target:手机号* }* @returns {Type} 运营商名称* @desc 根据目标对象获取运营商*/
function matchedNumber(data){return '返回对象'
}
方法块注释特殊参数
如果描述不能描述清楚,添加例子来描述。
如果方法中有异常处理,标记异常处理注释
/*** @method* @param {Type} data 目标对象* @returns {Type} 运营商名称* @desc 根据目标对象获取运营商* @throws {string} 抛出'Error'异常* @example* add(1, 2); // 返回3*/
function matchedNumber(data){return '返回对象'
}
如果有返回值增加@returns 如果没有省略此属性
参数和返回值类型Type:string、boolean、number、object、array、function
文件注释
在文件头部增加文件注释
/*** @file LBS控制器* @author limingle* @copyright Synway SFE* @createDate 2017-10-16 09:40:11*/
变量注释
将关键的变量进行特殊注释,生成到文档中
/*** @var {object}* @desc 变量定义* @property {string} a 属性a* @property {string} b 属性b*/
var foo = {a: 'a',b: 'b'
}
常量注释
将关键常量进行特殊注释,生成到文档中,如果有默认值增加@default
属性
/*** @constant {string}* @default #000* @desc 常量定义*/
const COLOR_WHITE = '#fff';
枚举注释
用于url列表或者颜色枚举值,一般用于配置文件中
/*** @enum {number}* @desc cgi常见的返回码*/
var RETCODE = {/*** @desc 未登录*/NOT_LOGIN: 100000,/*** @desc 参数错误*/PARAM_ERROR: 100001,/*** @type {string}* @desc 未知错误*/UNKOWN_ERROR: 'unkown'
}
类的注释
默认情况先一个function就是一个类
ES6中使用Class来表示一个类
我们项目中使用class.js来实现类,在我们项目中使用类注释时需要在@class
后边增加类名,不要jsdoc无法自动识别类名
/*** @class* @classdesc 这是对myClass类的描述* @desc 这是对myClass类的构造函数的描述*/
function myClass() {...
}
或者
/*** @class LBSControllerCom* @classdesc LBS控制类* @desc 初始化ws*/
var LBSControllerCom = Com.extends({})
类的属性
类的属性和变量都会生成到jsdoc文档的Member模块中,在类中使用属性标识
var LBSControllerCom = Com.extends({/*** @member {string}* @desc 这样标识类的属性*/foo1 : 'a',init: function() {}
})
参考链接:
JSDoc Guide
Javascript注释规范相关推荐
- JavaScript编码规范[百度]
JavaScript编码规范 1 前言 2 代码风格 2.1 文件 2.2 结构 2.2.1 缩进 2.2.2 空格 2.2.3 换行 2.2.4 语句 2.3 命名 2.4 注释 2.4.1 单行注 ...
- java 注释 超链接_java_Java代码注释规范详解,代码附有注释对程序开发者来 - phpStudy...
Java代码注释规范详解 代码附有注释对程序开发者来说非常重要,随着技术的发展,在项目开发过程中,必须要求程序员写好代码注释,这样有利于代码后续的编写和使用. 基本的要求: 1.注释形式统一 在整个应 ...
- JavaScript 代码规范
所有的 JavaScript 项目适用同一种规范. JavaScript 代码规范 代码规范通常包括以下几个方面: 变量和函数的命名规则 空格,缩进,注释的使用规则. 其他常用规范-- 规范的代码可以 ...
- JavaScript(一)—— 初识JavaScript/注释/输入输出语句/变量/数据类型
本篇为 JavaScript 系列笔记第一篇,将陆续更新 文章目录 一.初识 JavaScript 1. JavaScript 是什么 2. JavaScript 的作用 3. HTML.CSS 和 ...
- JavaScript 编码规范大全-Eslint(持续更新,欢迎关注点赞加评论)
JavaScript 编码规范大全(持续更新,欢迎关注点赞加评论) 文章目录 JavaScript 编码规范大全(持续更新,欢迎关注点赞加评论) 前言 0. 相关工具 1. 类型 2. 引用 3. 对 ...
- JavaScript编程规范-有利于效率和可读性
JavaScript编程规范 类型 对象 数组 字符串 函数 属性 变量 条件表达式和等号 块 注释 空白 逗号 分号 类型转换 命名约定 存取器 构造器 事件 模块 jQuery ES5 兼容性 性 ...
- 基础的JavaScript编码规范
/** 前言* 这个文档摘自Nicbolas C Zakas(担任过雅虎首席前端工程师) 著作 <编写可维护的 JavaScript>,下面是一些摘要* 这个文档讲了一些很基本的编写Jav ...
- 规范自己的JavaScript书写 – Dojo Javascript 编程规范
前言 良好的JavaScript书写习惯的优点不言而喻,今天彬Go向大家推荐Dojo Javascript 编程规范,相当不错的 Javascript 编程风格规范,建议大家可以借鉴一下此规范编写 J ...
- 前端代码编码和设计规范系列——JavaScript编程规范
1文档信息 条目 内容 项目编号 通用 项目名称 通用 标题 JavaScript编程规范 类别 规范文档 当前 试用草稿 摘要 当前版本 V1.0 日期 2015/11/9 作者 徐维坚(xuwei ...
- JavaScript => JavaScript编码规范指南
JavaScript 编码规范指南 以下文档大多来自: Google JavaScript 编码规范指南 Idiomatic 风格 对于未提及的事项可以参考airbnb的JS编码规范 airbnb/j ...
最新文章
- leetcode-455 分发饼干
- 一维正态分布、二维正态分布的matlab实现
- 高德地图android4,Android高德之旅(4)我的位置
- 我眼中的计算机,我眼中的计算机-计算机开机背后的故事
- hash函数查找和ASL计算
- Nginx服务器之负载均衡策略(6种)
- AndroidStudio_安卓原生开发_自定义蒙板弹出框WaitDialog---Android原生开发工作笔记134
- Android 代码名字-API级别-版本号-NDK版本对应关系
- 如何用计算机录视频,如何用电脑录视频?
- 关于日期插件在chrome中出现被遮挡的问题
- 妹子说头像爬的太慢?升级到多线程程序爬取头像
- java cms 垃圾回收_了解Java垃圾自动回收
- 无需安装Microsoft Office和Adobe实现办公文档操作,Spire.Office免费资源清单一览
- MySQL Key的含义
- 计算机模型不能预测未来,预测未来是一门艰深的艺术
- 【C语言答案】第七次练习---二维数组简单函数
- 使用Python和OCR进行文档解析的完整代码演示(附代码)
- 如何搭建云进销存-采购管理系统?
- Norton PartitionMagic
- 国家基础地理信息中心编制完成新版世界地图
热门文章
- 用AdobePageMaker制作PDF文档
- 机械专业与计算机专业哪个专业更好,机械类哪个专业好
- 机械专业怎么学matlab,MATLAB在机械类专业课教学中的应用
- android助手最新版本,Android 开发助手功能及版本介绍
- python处理地震sac数据_自己开发的一个SEED格式地震数据转换为SAC格式数据,并完成世界时整天波形合并的Python脚本...
- 桌面壁纸被计算机管理员禁用,Win7更改桌面壁纸时出现“此功能已被禁用”如何解决...
- 微软服务器补丁管理软件,微软IT的补丁管理-MicrosoftDownloadCenter.PDF
- 屏幕保护程序命令行参数
- java捕鱼达人源码_捕鱼达人java源码(完整功能)
- 【原文件】辞海(第六版彩图本) pdf