指导文件

指导性的文件，用于指导项目编码规范、文档编写规范以及注意事项。

1. 所有描述性质的介质第一服务对象为人类，因此可读性是第一位的。(描述性质的介质包括但不限于 程序代码、文档、说明文件等)
2. 在不违背可读性的情况下，应尽量符合 编码规范（例如 ESLint）、成文标准（例如标点符号使用规范）。
3. 在不违背可读性，满足编码规范（最基本的不能报错，报警告）的情况下，应尽量满足可维护性，方法包括但不限于 测试用例、注释、文档以及高度工程化、模块化的设计等。
4. 在不违背可读性，满足编码规范，且可维护的情况下，应尽量做到雅俗共赏，即让低水平的人也能理解。

说明性文件记录格式

非格式化的数据

直接用自然语言进行记录

格式化数据

如果数据本身较为简单，不需要频繁编辑，二次处理，可以直接以表格形式呈现。倘若数据本身较为复杂，用表格显示会显得十分臃肿，这时我们一般会将其用 JSON/XML 进行记录，对于数据量非常巨大的数据集，我们会将其放在数据库中。

考虑到面向 Web，故采用 JSON 作为该类数据的优先显示方式，原因如下:

• JSON 易于(人类)阅读
• JSON 易于(机器)处理
• 用 JSON 记录其实也有一些缺点，比如链接不能被点击，很难实现 i18n，但它是（我觉得）当下 Github 支持的，既方便阅读又方便处理的最优解，它达到了一种平衡。

与此同时，考虑录入效率，如果使用文本编辑器进行编辑，建议使用 JS 风格的 JSON 进行记录，原因如下:

• 因为是由人类完成书写，JSON 过于严格的格式要求（key 要用双引号引起来，String 要用双引号而不能是单引号）不利于人类快速录入，同时也降低了可读性。
• js 风格的 JSON 可以很轻松的和 json 风格的 JSON 完成互转
• js 风格的 JSON 其实不是 JSON，是 Javascript 的 Object/Array，但是因为在此处和 JSON 用途等效，所以称其为 JSON

开源项目许可证的选择

• 单机程序 - GPLv3
• Web 程序 - AGPL
• 类库 - LGPL
• 文档 - CC 4.0

开源项目质量控制

• 单元测试 - jest.js
• UI 测试 -
• 漏洞扫描 -
• 代码风格 -
• 代码规范 -
• 文档编写 -
• 浏览器兼容性验证 -
• 分辨率自适应验证 - ResponsivelyApp

补充说明

可读性的定义

指易于理解的程度。

• 高可读性意味着能让人类用更短的时间理解。

可维护性的定义

指对其进行修改的难度。

• 高可维护性的项目必须也必定是高可读性的。
• 高可维护性的项目应该能用尽可能少的人力、时间完成维护、二次开发。
• 理论上讲，高可维护性的项目应该 bug 更少。