项目结构

下面是社区正在广泛使用，但未成规范的一些约定。我们可能在某些时候删除一些条目或是强制要求另一些条目。现在，它们只是方便新人上手的建议。

文件大小写

文件名首字母应该大写。

原因：模块名称只能以大写字母开头。新人经常会问：文件和模块的对应关系是什么、为什么 draw.res 文件对应的是 Draw 模块。而且新手有时候会尝试用小写字母开头的标识符来表示模块。使用 Draw.res 让对应关系更加直接，这也有助于避免在不加大写的情况下显得很别扭的某些文件名，例如 uRI.res。

忽略 .merlin 文件

这是构建系统生成的文件。你不应该手动编辑它，不要把它提交到代码仓库里。

原因：.merlin 文件是给编辑器工具用的。文件内容包含绝对路径，绝对路径无法跨平台使用（例如 Windows 的路径是不一样的）。

文件夹

尽量不要嵌套太多文件夹。让项目保持扁平化、减少文件数量（提示：可以使用嵌套模块）。

原因：文件系统是一棵树，但是代码的依赖关系是一个图。正因如此，一般不存在完美的文件与目录组织。虽然把相关的文件放在一个文件夹里还是有价值的。我们建议你不要把时间浪费在纠结这些低性价比的问题上，要把精力放在完成工作上。

第三方依赖

尽可能少地使用第三方依赖。

原因：一门需要编译的静态类型语言不能像动态语言那样轻易地建立其依赖关系模型，特别是当我们还在使用 NPM/Yarn 的时候（这是为了减少中期学习成本）。保持简单和精简的依赖关系有助于降低冲突的可能性，例如菱形依赖、接口冲突等。

文档

要有文档！多花点功夫让文档更完善且专业（样例、陷阱），而不是只有花哨的外观。多写点样例，但要避免使用 foo、bar 这种名字，总有更明确的命名，没必要那么抽象或者一般（这是 API 文档应该做到的）。写博客文章的时候不要重复文档的内容，可以描述新旧版本的变化和原因（例如它本来是个组件，现在是个函数，因为...）。

原因：新手很难分辨出一个库是真的简单好用，还是只是看起来好用而已。为了营造良好的社区环境，不要一心只想卷赢别人的库。请传播这样的理念，但也请使用你的判断力。

PPX 和其它元编程工具

尽量少用或者不用。PPX 除非用在非常通用（例如日志输出、属性访问器、生成序列化/反序列化代码）的场景，否则容易给新手带来学习上的阻碍。新手已经要学习语法、语义、类型、构建工具、FFI 了，再让他们学这种每个库都不同的语法变换规则实属多此一举。宏的侵入性越高代码自身的表意就越差，因为最重要的部分可能已经被藏在其它地方了。

范式

不要滥用炫酷的功能。给未来的 API 留一些变动的空间，但是不要过度设计。

原因：简单易懂的代码能帮助新人更快上手，甚至为你贡献代码。贡献代码是他们最佳的学习方式。得到这些额外的帮助可能比一个炫酷的语言特性能带来更高的收益。但在平时的非正式项目中也要多多尝试语言的新特性，你可能会不经意间发现新的代码架构方式。

发布

如果你要发布一个 JS 库的封装，不要发布 JS 的构建产物。如果你认为 JS 用户可能会使用它，建议把构建产物发布在 lib/js 中。这特别适合你想把一个 JS 库逐渐重构成 ReScript，但又不想破坏存量 JS 用户的情况。

在 package.json 中把关键字 "rescript" 添加到 keywords 字段中。这能让我们未来能够更容易找到这个库。

原因：对你的 JS 用户好一点，他们会是你未来的 ReScripter。