写前端文档

我想前端开发过程中, 无论是团队开发, 还是单兵做站, 有一份开发文档做规范, 对开发工作都是很有益的.

成都创新互联秉承实现全网价值营销的理念，以专业定制企业官网，网站建设、网站制作，小程序定制开发，网页设计制作，移动网站建设，全网营销推广帮助传统企业实现“互联网+”转型升级专业定制企业官网,公司注重人才、技术和管理，汇聚了一批优秀的互联网技术人才,对客户都以感恩的心态奉献自己的专业和所长。

前端文档缺失的原因

前端开发的文档相信大多数情况下都没有后端的服务描述详细，而大多数测试也仅仅在黑盒测试，所以很多情况下对这片文档的描述都廖廖无几。

1、前端开发的代码分散——没有规范化，没有很好的设计，大多数人仍以业务为主的开发方式。

2、测试人员对前端仍然处于黑盒测试，有没有文档都不影响到他们的测试进程。

3、一旦业务定型，用传统方式的文档模式，很难复制到前端开发来。——改变了开发方式（从作坊式到规范化）让人难以适应。

尝试对症下药

对于代码分散的问题需要从源头解决。从规范化开始，试点从头到尾惯穿规范化，强制的约定，使代码质量提高。
这一块需要下大力气，中间加入设计review、代码review等环节。需要注意的是粒度把控，即什么是必须的，什么是可选的，什么是约定的等有共识。

1、功能描述

开发前的工作，对编码者来说必须收集需求。对于使用者来说，能够知道写这个代码的目的是什么，解决了什么问题，还有什么问题没有解决，或需要改进。

2、设计描述

分享你的思想，这很重要，一个成熟的开发人员看开码的时候很多时候不是看你实现如何如何，而是看你的设计。

3、API描述

使用者快速上手。接口是代码的眼睛。命名要严谨，不能说也可这样，也可那样。经验告诉我们，接口做得不好，历史原因就会多。

4、demo/snippets

给使用的人copy/paste没什么不好。

5、使用指南

例如库的使用指南等手册。或者说一个简单的上手教程

文档该由谁来写？

从理论上看，文档都应该由编码者来写，其实不然。一个软件的周期，可以分为：开发前，开发时，使用时，测试时，维护时。
那么各时间段上应该有不同的人来参与。缩小些范围来看的话，应该将：

1、开发前收集需求由大家参与。实现者收集后存档到文档里。此为开发目的与预期。

2、开发时的API描述，设计描述主要由编码者来实现。

3、开发后/维护时的demo及snippets可以由使用者来完善。

设计文档是否能自动化生成

代码注释(现在一般都用java doc)可以生成接口文档。

以往都必须自己画设计图，配上描述。那么理论上这块也应该可以通过注释加入设计的描述，通过文档生成的工具自动生成设计图。这样应该方便多了。

当前题目：写前端文档
文章来源：http://www.shufengxianlan.com/qtweb/news29/78379.html

网站建设、网络推广公司-创新互联，是专注品牌与效果的网站制作，网络营销seo公司；服务项目有等

广告

声明：本网站发布的内容（图片、视频和文字）以用户投稿、用户转载内容为主，如果涉及侵权请尽快告知，我们将会在第一时间删除。文章观点不代表本网站立场，如需处理请联系客服。电话：028-86922220；邮箱：631063699@qq.com。内容未经允许不得转载，或转载时需注明来源： 创新互联