贡献规范

致贡献者

我们热烈欢迎熟悉各类微积分数值求解相关科学计算库的开发者加入本项目，贡献代码并分享宝贵的经验。同时，我们鼓励初学者通过参与开发和改进文档来学习和掌握微积分相关的数值方法。在本项目中，我们希望无论是有经验的开发者还是初学者，都能通过查阅项目文档、示例和代码找到自己感兴趣的贡献目标。

我们衷心感谢所有为本项目做出贡献的开发者。无论是提交代码、完善文档，还是提供宝贵的反馈，你的每一份努力都让这个项目变得更好。你们在开发过程中的热情与智慧不断推动项目前进，也为社区带来了更多合作的机会。感谢你们的支持与付出，期待与大家携手取得更多成果，让这个项目迎来更加光明的未来！

1. 代码风格

• 统一采用 MoonBit Toolchain 的格式化风格，通过运行以下命令来自动格式化代码。

  moon fmt

  请确保在提交代码之前，使用 moon fmt 格式化代码，以保持一致的代码风格。

  或者，可以使用 ready_to_pr.sh 脚本来自动格式化代码、运行检查、生成测试覆盖率文件和 .mbti 文件。

2. 命名约定

2.1 变量命名

• 采用 小写字母和下划线 分隔（例如：my_var）。
• 变量名应具有描述性，能够准确反映其用途。

2.2 函数命名

• 使用 小写字母和下划线 分隔（例如：calc_total_price()）。
• 函数名应简洁且具有描述性，能够清晰表达函数的功能。

2.3 Struct 和 Trait 命名

• 使用 首字母大写的驼峰式命名（例如：MyStruct、MyTrait）。
• 命名应直观地反映该结构体或特征的功能或角色，避免使用过于抽象或不具描述性的名称。

2.4 常量命名

• 注意： 由于在 MoonBit 的语境下，“变量”通常称为“binding”，且默认是不可变的，只有添加 mut 关键字才能使其可变。因此，常量和“变量”之间没有严格的命名差异，保持一致性。
• 常量名采用 全小写字母和下划线 分隔（例如：machine_dbl_epsilon）。
• 常量名通常以第一个单词作为前缀，表示常量的用途或分类。例如，machine_dbl_epsilon 中的 machine 表示与机器相关的常量。
• 常量名应简洁且具有描述性，便于其他开发者理解。

2.5 Result 的 Err 构造内容和 Err Code

• 采用 全大写字母和下划线 分隔（例如：E_MAX_ITER）。
• 构造内容通常以字符E作为前缀，表示其用于 Err 构造或者错误代码。
• 构造内容应简洁且具有描述性，便于其他开发者理解。

3. 注释

• 简洁性：注释应简洁明了，只包含必要的信息，避免冗长和不相关的内容。
• 一致性：使用一致的术语和风格，避免在不同地方使用不同的方式描述相同的概念。
• 清晰性：确保注释易于理解，避免复杂的术语或模糊的表述。应使任何阅读代码的人能够快速理解注释的意图。
• 准确性：注释必须准确反映代码的功能和目的，避免与代码行为不符的描述。
• 更新性：随着代码的变更，注释也应随时更新，确保注释与代码同步。

我们鼓励开发者采用 MoonBit LSP 提供的 AI 代码注释生成来提升注释的编写效率，但需要开发者对 AI 生成的内容进行审核，以确保其对方法、结构体和特征的解释是正确无误的。

4. 文件规范

4.1 文件夹命名

• 对于大的功能模块，请使用小写字母命名的文件夹（包）。

• 文件夹名称应简洁、具有描述性，并使用下划线（_）分隔单词。请避免使用数字和特殊字符。

  例如：

  • 微分相关功能：diff
  • 导数相关功能：deriv

4.2 文件划分

• 文件应该按功能划分，每个文件专注于特定的功能。文件名使用小写字母和下划线。

• 文件名应具备描述性，清楚反映该文件所实现的核心功能。

  例如：

  • gauss_kronrod.mbt：实现带克龙罗德扩展的高斯求积。
  • adaptive_quadrature_gk.mbt：使用带克龙罗德扩展的高斯求积实现的自适应积分。

• 注意：在文件命名中（除了在@internal 中不可避免的情况），请避免使用过于通用或模糊的名称，如 utils.mbt，请尽量使文件名与其功能或模块相关联。

5. 提交规范

5.1 提交信息

• 在提交前请使用 ready_to_pr.sh 脚本来自动格式化代码、运行检查、生成测试覆盖率文件和 .mbti 文件。

• 每个提交应具有清晰的描述，说明此次提交所做的变更。

• 提交信息应使用英文，并遵循简短、精炼的原则。

• 使用 fix:，feat:，refactor: 和 doc: 等前缀来区分提交的类型

  例如：

  fix: fix bug in something
  feat: add feature for something
  refactor: refactor something
  doc: add docs for something

5.2 提交频率

• 尽量保持每次提交都很小且聚焦于一个功能或修复。
• 不要一次性提交大规模的更改。

6. 代码审查

• 非项目维护者和合作者在修改moon.mod.json内的依赖和版本号前，请先联系维护者或者合作者。
• 所有的代码提交都必须经过代码审查。
• 在审查过程中，关注代码质量、风格、性能和安全性。
• 审查者应提供建设性的反馈，帮助改进代码。