首页百科大全正文内容

前端架构之路（4）

百科大全

更新时间：2025-10-06 05:41:5744

admin管理员组
文章数量:1794759

前端架构之路（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. 后续

上一篇：前端开发规范

下一篇：构建工具 for teamwork

参考文章：

JSDoc 中文文档

更多博客，查看 github/senntyou/blogs

作者：深予之 (@senntyou)

本文标签：之路架构

版权声明：本文标题：前端架构之路（4）内容由林淑君副主任自发贡献，该文观点仅代表作者本人，转载请联系作者并注明出处：http://www.xiehuijuan.com/baike/1686500554a74482.html，本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌抄袭侵权/违法违规的内容，一经查实，本站将立刻删除。