前端架构之路(4) - 前端开发文档
前端开发文档
1. 为什么需要 “前端开发文档”
上一节讲到开发规范,不以规矩,不成方圆,团队开发离不开规范,这一节讲的开发文档是对开发规范的一个补充。
从目的上讲,规范与文档都是为了降低团队的协作成本和维护成本,提高开发效率和质量,保证不会因为开发人员的变动而产生较大的影响。
2. 哪些需要形成文档
2.1 注释(只讨论 js
)
随着前端的发展,文档已经慢慢的变得不可或缺了,并由社区的努力而形成了 JSDoc,类似 JavaDoc 和 PHPDoc。
2.1.1 什么是 JSDoc
JSDoc 是一个根据 javascript 文件中注释信息,生成 JavaScript 应用程序或库、模块的 API 文档 的工具。你可以使用他记录如:命名空间,类,方法,方法参数等,并且很多编辑器和 IDE 都是直接支持智能提示的。
2.1.2 JSDoc 注释示例
JSDoc 注释一般应该放置在方法或函数声明之前,它必须以 /**
开始,其他任何以 /*
,/***
或者超过3个星号的注释,都将被JSDoc解析器忽略。例如:
/** * Book类,代表一个书本. * @constructor * @param {string} title - 书本的标题. * @param {string} author - 书本的作者. */ function Book(title, author) { this.title=title; this.author=author; } Book.prototype={ /** * 获取书本的标题 * @returns {string|*} */ getTitle:function(){ return this.title; }, /** * 设置书本的页数 * @param pageNum {number} 页数 */ setPageNum:function(pageNum){ this.pageNum=pageNum; } };
2.1.3 JSDoc 标签一览
{@link: ...}, {@linkplain: ...}, {@linkcode: ...}, {@tutorial: ...}
: 内联标签@abstract
: 抽象,必须由继承者实现(或者覆盖)@access
: 访问级别(private、public或者protected)@alias
: 别名@augments
: 参数@author
: 作者@borrows
: 借用@callback
: 回调函数@classdesc
: 类描述@constant
: 常量@constructor
: 构造函数,可以使用new创建一个实例@constructs
: 构造@copyright
: 版权@default
: 默认值@deprecated
: 弃用的@desc
: 描述@enum
: 枚举值@event
: 事件@example
: 范例@exports
: 模块导出(模块化)@external
: 外部模块(模块化)@file
: 文件@fires
: 可触发的事件@global
: 全局对象@ignore
: 忽略@inner
: 内联对象@instance
: 实例@kind
: 标识类型@lends
: 遍历属于同一个标识的所有属性@license
: 软件授权@link
: 内联@member
: 成员@memberof
: 属于某成员@method
: 方法@mixes
: 合并@mixin
: 最小化@module
: 模块(模块化)@name
: 名称@namespace
: 命名空间@param
: 参数@private
: 私有的(访问控制)@property
: 属性@protected
: 受保护的(访问控制)@public
: 公开的(访问控制)@readonly
: 只读的@requires
: 依赖(模块化)@return
: 返回值@see
: 引用@since
: 开始于@static
: 静态的@summary
: 概述@this
: 解释this关键字@throws
: 可能抛出的异常@todo
: 待办事项@tutorial
: 引用指导手册@type
: 类型@typedef
: 自定义类型@variation
: 区分不同的对象具有相同名称的@version
: 版本
2.1.4 把注释生成文档的工具
- jsdoc: 官方提供的工具
- documentation.js: 另外一个可供选择的工具,支持生成
html
,markdown
,json
- dox: tj 大神的作品
2.2 业务逻辑、更新日志与备注
另外一个需要记录的信息就是业务逻辑、更新日志与备注。
2.2.1 业务逻辑
有些比较复杂的业务逻辑不太适合放在注释里面,需要单独写逻辑文档,以备后面查看。
有时候,有些逻辑并不是简单的用文字描述就能说的清楚的,还需要图表或者思维导图的辅助。
2.2.2 更新日志
更新日志也是一个比较重要文档,能够方便查找更新状态、时间、开发人员等。
2.2.3 备注
如果有额外的一些信息,需要用文档备注一下。
3. 后续
上一篇:前端开发规范
参考文章:
更多博客,查看 https://github.com/senntyou/blogs
版权声明:自由转载-非商用-非衍生-保持署名(创意共享3.0许可证)
相关推荐
lxhuang 2020-11-03
小焊猪web前端 2020-10-24
南昌千网科技 2020-10-18
liduote 2020-10-16
PncLogon 2020-09-24
趣IT 2020-09-22
颤抖吧腿子 2020-09-04
franktaoge 2020-08-15
xxuncle 2020-07-04
viciousDear 2020-06-14
liangjielaoshi 2020-06-10
小秋 2020-11-12
杏仁技术站 2020-10-23
杏仁技术站 2020-09-18
拾光璇旅 2020-09-17
lfbooo 2020-09-09
Herorong 2020-08-25
anaction 2020-08-17
风萧萧梦潇 2020-08-17
PncLogon 2020-08-16
MrHaoNan 2020-07-31