软件及文档开发编写规范

如果软件或者文档乱七八糟，任何人看起来都会头疼，时间长了，自己都看不懂自己曾经写过的代码了。有自己的软件命名或者文档命名规范，一方面是为自己整理一个清洁的电脑环境，另一方面也是为后来者提供一个干净清爽易读的软件开发环境，至于代码方面的规范以及命名规则，也应该参考大公司的团队协作及编码规范。

1.文件夹

文件夹的组织要有一定的逻辑，方面查找和分享。
(1) 首先会在剩余空间较大的磁盘中，新建一个已自己的名称缩写命名的文件夹，比如:D:\xm,我所有的工程项目及文档，都会放到这个文件夹中，算作自己的工程目录。
(2) 在这个工程目录下，每一个项目都会以单独的文件夹来命名，比如工程测试，那就新建一个叫test的文件夹，放到xm工程目录中。
(3) 然后在这个test文件夹中，新建一个 “目录说明.txt” 或者是 “目录说明.md”,对这个工程目录进行必要的说明，比如这个test项目包含了多个代码工程，project1、project2,还包括了一个doc目录，doc目录主要存储一些文档等，及其他的必要的文件及文件夹的说明。

2.代码

无论是java、python、还是nodejs等，都有其代码命名及注释的规范要求，使用同一的风格及规范，有助于代码的交流，更重要的是给自己和同事提一个醒，不至于自己写的代码，过个几天，在回来看的时候，就会怀疑是不是自己写的了。所以，在编写代码时一定要符合规范，参考文章中有诸多命名规范，应该仔细阅读。下面几篇文章讲了阿里巴巴等公司对于编写Java代码的规范，请仔细阅读并按规范编写代码。

注意：一定要随时写注释
注意：一定要随时写注释
注意：一定要随时写注释

3.README.md

每一个工程或者代码目录，都要有个一个ReadMe.md文件进行本工程的说明，主要包括但不限于以下几方面：
(1) 项目技术路线。此项内容主要编写这个工程中用到的主要的技术和框架，使用到的插件及其版本，必要时应提供插件的相关地址。
(2) 运行打包部署说明。主要说明如何调试和部署此项目，比如java项目，使用maven打包时，应说明打包的过程，执行的命令行：maven clean package,文件放置的目录等。
(3) 接口说明。如果使用java,可以使用swagger技术，直接在函数上说明接口的含义与类型。如果没有这个工具，则可以在ReadMe文件中通过文字进行说明。一个接口应至少包含三个方面：参数、返回值及其他说明(算法啊、思想啊、注意事项等)

4.软件安装

软件安装的位置，一般不应该安装在C盘，通常在离C盘最近的一个磁盘，比如D盘(有些电脑没有D盘)新建一个soft文件夹，通常将软件安装到这个文件夹中(如果有其他的习惯，亦可以使用，但尽量保持在一个统一的文件夹中安装所有需要安装的软件)。

5.学习文档编写规范

这个不知道该不该说，因为有些人有很好的博客编写习惯，有些人没有。这里权当是普及知识吧，喜欢的人有自己喜欢的方式，记录自己的生活，也不局限于这里写的东西。这里推荐使用markdown编写学习文档，虽然它不及word文件粘贴图片方便，但是它符合兼容html语法，适合跨平台、跨语言、跨网站进行交流。很多的博客网站，比如简书、csdn、博客园等，都支持markdown语法。而且这种格式适用于适用git进行版本管理，相反因为doc是二进制格式，而二进制格式是git最不擅长管理的。像Github、Gitlab以及AzureDevops等，都支持在线查看md文件。还有一点，虽然md不支持直接嵌入一个图片，但是他也支持图片链接啊。只要符合md语法，就可以在博客中嵌入一张图片。

(1) 文档命名格式
这里我推荐的格式是文档编写格式为，一篇有意义的命名的以md为后缀的文件，外加在此目录下同名的文件夹，其内放和此文章有关的图片。
错误示范：

这里的文档文件名丝毫没有意义和主题，我推荐是以主题的名字命名文档，而不是用日期的方式，比如：”git软件操作指南.md”，这种文章一般人都知道在写些什么，多篇主题，就分割为多篇文章。而且文章相关的图片都放在了一个文件夹下，如果文章数特别大的情况下，图片变得非常的难以管理。

md文章，附带一个同名文件夹的方式也是借鉴了hexo生成静态博客网站的做法。比如我存放文档的文件夹名叫bibichuan_document,该文件夹下有个多篇md文件，也有多个和md文件同名的文件夹，其中存放的是该md文件相关的图片。hexo中使用:hexo new psot “文章名” 在生成文章的时候，就是生成了一篇 <文章名.md> 以及同名文件夹，放在同一目录下。markdown中嵌入图片时，以相对目录的形式嵌入。

(2) 参考文章
解决任何一个问题，或者编写任何一个文章，都不可能是完全独立自主的创造，或多或少的都会借鉴别人的思想或者方法，所以在编写文章的时候就一定要写参考文章。参考文章的格式，我觉得可以适用markdown嵌入网址的形式。

1
2
3
4
5
6
7

文章内容
------

参考文章：
1.[参考文章名](文章http地址)

这样在阅读起来就类似于：

在网站上就可以通过参考文章进入相应的页面，而且简洁。编写参考文章，可以是在文章的最后，也可以是在每一个大标题下，或者小标题下，只要能区分开就好了。

编写一篇好的，排版清晰的，能让人一下子读的懂的文章，也是一种能力。

6.项目计划

项目计划的制定，首先由项目经理分配任务及内容，并规划时间节点。在项目设计书缺失的情况下，由个人根据目前的任务及内容，在周一上报本周工作计划，并由项目经理(产品经理、组长)针对任务计划、个人能力、时间节点进行计划调整，分配到每一人中，所有人按计划执行，并适时加班。项目计划应充分考虑技术的难易程度，个人的技术水平，以及时间成本。任务应具体到每一天。
每周五进行项目回顾，并和甲方进行沟通汇报任务进度。记录甲方需求的更改，在不改变现有计划及任务安排的前提下，尽可能的满足甲方的修改需求，比如界面的颜色，字体的大小，文字的内容，超出相应的范围，应在完成此次版本迭代之后，在下一个版本中，对甲方的重大需求，进行实现。

项目计划的设立，要在和甲方充分沟通的基础上，完全明白甲方需求的前提下，进行项目计划的编写，在前期项目需求不明悉的时候，要一而再再而三的和甲方进行需求确认，有条件的可以将设计图，项目需求计划书等给甲方进行签字确认

项目计划应在Excel表包含已下内容：
(1) 项目阶段
(2) 计划开始日期
(3) 计划天数
(4) 计划结束日期
(5) 实际开始日期
(6) 实际天数
(7) 实际结束日期
(8) 备注

7.测试及优化

关于测试,可以说的内容有很多，测试的分类包括白盒测试、黑盒测试和灰盒测试等，还有一些测试用例等，这里就不详细展开了。对于代码编写人员来说，首先要做的就是自测，如果自己会写测试用例，或者是测试计划，可以使用代码进行测试，如果不会编写测试用例，那就要从功能角度出发，逐一测试每一项功能，每一个按钮的正确与否，最终展示效果是否符合设计书要求，包括但不限于功能的可用性，交互的合理性等。自测的内容大致要求包括：

(1) 不能出现常见的bug，比如按钮功能无法使用，服务器没有响应，界面上出现NaN、undefined等用户看不懂的字符。

(2) 在编写完成一个功能之后，需要进行十次及以上的测试。

(3) 在单一功能测试结束后，应进行集成测试，至少测试五遍以上的集成测试。

(4) 自测完成后，应主动要求他人进行测试。邀请团队测试时，不能详细说明使用方法，应该让用户在完全不知道的情况下，对任意功能进行随意测试，达到的目的就是测试交互的合理性以及是否有不可见的bug等。

(5) 经过团队测试后，还可以进一步的提交项目经理(或其他部门人员)进行测试。项目经理或者时专业测试人员，应按照设计书的内容，逐条，逐项进行内容测试，保证最终交付的系统，符合设计书的要求。项目经理或者专业测试人员给出测试报告，包括bug内容、测试过程、bug截图，根据测试报告内容，分为低级、中级和高级bug，bug修复的紧急程度分为普通、危险、紧急。根据测试报告的数量多少，对程序员工作进行打分。

低级bug包括：功能无法使用、界面错乱、文字不正确、出现NaN等错误，不符合设计功能要求。
中级bug包括：交互逻辑问题、数据丢失
高级bug包括：页面偶尔出现崩溃问题

8.综合测评

(1) 制定相应的项目计划，将计划分解为单人单天或者是多天的任务，详细记录开始时间、结束时间等。由项目组长根据公司安排，以及和甲方多次沟通之后，确定项目计划、本月计划、本周计划并细分到每一人每一天的计划。任务下发后，由相关人员根据自身能力，及时间安排反馈计划中的困难和不足，组长及时回答和解决相关的内容，在不影响项目进度的前提下，酌情调整计划安排。

(2) 根据项目计划安排，分别进行一天的打分。每日下午下班前，汇总日报及提交代码内容，由组长根据项目计划及提交的内容，判定工作内容的合格程度，未完成的工作计划，酌情加班处理。采用减分制，总分10分，未按项目计划完成减5分，一周工作完成后，复盘本周工作计划，及项目进度，根据一周工作进度及安排，在完成本周工作目标的基础上，将本周内由于当日未完成工作计划减去的分数，全部复原，如果能超前完成任务计划的内容，将按每天增加5分的机制，进行积分奖励。

(3) 根据测试结果，由组长进行最终测试打分。每发现一个低级bug，减掉3分，每发现一个中级bug减掉2分，高级bug酌情进行减分。

(4) 根据文档编写要求，一星期至少2篇学习文档，每少一篇扣除1分，多写一篇增加1分。每篇文档不得雷同，不得抄袭，重复率不得高于50%，否则不予积分。

(5) 按天进行积分，按月进行分数汇总。采用末位淘汰制，取所有人员的平均值，凡是低于平均值的，酌情扣除相应的工资，并将扣除的工资分发给平均分发给月累计分数高于平均值的同事。

9.文件及软件版本

(1) 文件名称由四部分组成：第一部分为项目名称，第二部分为文件的描述，第三部分为当前软件的版本号，第四部分为文件阶段标识加文件后缀，例如：项目外 包平台测试报告 1.1.1.051021_beta_b.xls，此文件为项目外包平台的测试报告文档，版本号为：1.1.1.051021_beta。

如果是同一版本同一阶段的文件修改过两次以上，则在阶段标识后面加以数字标识，每次修改数字加1，项目外包平台测试报告 1.1.1.051021_beta_b1.xls。

当有多人同时提交同一份文件时，可以在阶段标识的后面加入人名或缩写来区别，例如：项目外包平台测试报告 1.1.1.051021_beta_b_LiuQi.xls。当此文件再次提交时也可以在人名或人名缩写的后面加入序号来区别，例如：项目外包平台测试 报告 1.1.1.051021_beta_b_LiuQi2.xls。

(2) 软件版本主要包括下面四个部分

• 主版本号(1)：当功能模块有较大的变动，比如增加多个模块或者整体架构发生变化。此版本号由项目决定是否修改。
• 子版本号(1)：当功能有一定的增加或变化，比如增加了对权限控制、增加自定义视图等功能。此版本号由项目决定是否修改。
• 阶段版本号(1)：一般是 Bug 修复或是一些小的变动，要经常发布修订版，时间间隔不限，修复一个严重的bug即可发布一个修订版。此版本号由项目经理决定是否修改。
• 日期版本号(051021): 用于记录修改项目的当前日期，每天对项目的修改都需要更改日期版本号。此版本号由开发人员决定是否修改。
• 希腊字母版本号(beta): 此版本号用于标注当前版本的软件处于哪个开发阶段，当软件进入到另一个阶段时需要修改此版本号。此版本号由项目决定是否修改。