YunmengEnvs

Developer Guide

云梦环境项目主要旨在用于学术以及实验用途,因此在设计各种算法和方案的实现细节时,编码的清晰度是重中之重。
尽管如此,它的所有数值和算法在很多方面都与面向工业的 CFD 代码相似。


如何参与项目的开发

欢迎各位开发者参与云梦环境项目的开发,有以下几种方式可以参与:

  1. 参与开发

如果你对云梦环境项目感兴趣,想参与到项目的开发中来,可以先阅读开发者指南了解项目的开发流程,然后在项目仓库中提交你的代码。

  1. 反馈问题

如果你在使用云梦环境项目过程中遇到问题,或者有好的建议,欢迎在项目仓库中提交issues或者discussions

  1. 参与讨论

如果你对云梦环境项目有更深入的理解,或者想参与到项目的讨论中来,欢迎在项目仓库中提交discussions

  1. 参与文档编写

如果你对云梦环境项目有更深入的理解,或者想参与到项目的文档编写中来,欢迎在项目仓库中提交pull request


关于项目的发布流程

项目暂定发布在 GitHub;采用 Git 作为协作开发和版本控制工具;采用 Git Flow 开发模式;版本号采用 year.month.patch 格式。

功能提交

每个提交应该只包含一个逻辑上的更改或修复,这样可以更容易追踪和理解每个提交的意图。
建议将每个commit用时控制在 3 小时内,鼓励提高提交频率。
避免将多个不相关的更改混合在一个提交中,以免给代码审查和版本控制带来困扰。

提交信息的格式通常是:“[类型]: 描述”。

类型指这个提交所属类别,可以是 feat、fix、doc、style、refactor、test、chore 等。
描述是对提交的简短描述,应尽量清晰明了,突出关键信息。

提交信息应该描述清楚修改的内容,不要使用模糊的词汇。 尽量提供一些上下文信息,例如为什么做出这个更改、解决了什么问题、有什么影响等。如果有关联的问题(如GitHub Issue等)或任务,可以在提交信息中引用相关的编号。

Github原生开发

通过 github actions 和 security(code scanning)实现 linux、windows 平台下的 ci 方案。

通过 github issues 登记开发工作(保留feat、bug等开发足迹)。

通过 github discussions 进行团队沟通交流。
通过 issues 当然也可以讨论,不过更多是已确定的 feat 或 bug。

通过 github projects 进行开发计划和进度管理,控制版本发布。


关于项目的编码风格

在开发过程中培养代码工程素养,对代码 “有讲究”,有助于我们开发更可靠和好维护的模型模块:

对于单个概念,定义好其内涵外延;对于多个概念,梳理好其层次关系。映射到代码上,就是不同类的职责清晰划分。

但需要声明,不同的阶段对讲究程度要求是不一样的,如何抉择呢?这里可以引入一个参考度量:生命周期。 生命周期越长的代码,一定要写的越干净;临时使用代码,比如原型、脚本,就可以不讲究一些。 反过来,也正是干净的代码才能成就超长的生命周期。

在软件项目开发中,代码的规范性主要包括几个方面:

编码风格

云梦环境项目中主要参考 Google Python 风格指南,主要追求:

  1. 一致性:遵循统一的编码风格,使得代码易于阅读和理解。

  2. 易读性:代码应该易于理解,易于维护。

代码注释

我们完全不介意你的注释是代码的2倍、3倍 …,你的代码、你的成果,你想说什么、想说多少都可以。

日志

良好的系统,可以通过日志进行问题定为。除了在本地代码上复现、调试外,还要能够通过丰富合理的日志信息还原问题现场,发现错误位置和原因。

为什么打日志

什么时候该打日志?

  1. 经常以功能为核心进行开发,应该在提交代码前,可以确定通过日志可以看到整个流程;

日志分级

  1. ERROR。该级别日志发生时,已经影响了用户的正常使用,通常程序抛错、中止。主要类型有:
    • 所有第三方对接的异常(包括第三方返回错误码)
    • 所有影响功能使用的异常
  2. WARN。该级别日志不应该出现但是不影响程序继续运行的问题。主要类型有:
    • 异常:不明确异常,只进行了简单的捕获抛出,需要打印这种笼统处理的异常
    • 有容错机制的时候出现的错误情况
    • 找不到配置文件,但是系统能自动创建配置文件
    • 性能即将接近临界值的时候
    • 非预期执行:为程序在“有可能”执行到的地方打印日志
  3. INFO。该级别日志主要用于记录系统运行状态、等信息,常用于反馈系统当前状态给用户。主要类型有:
    • 不符合业务逻辑预期:打印关键的参数
    • 系统模块的入口与出口处:可以在重要方法级或模块级记录输入与输出
    • 对外提供的接口入口处:打印接口的唯一标识和简短描述,并且要将传入的参数原样打印
    • 调用其它系统接口的前后:打印所调用接口的系统名称/接口名称和传入参数/响应参数
    • 服务状态变化:程序中重要的状态信息的变化应该记录下来
    • 一些可能很耗时的业务处理:批处理,IO操作
  4. DEBUG。该级别日志的主要作用是对系统每一步的运行状态进行精确的记录。(该级别的日志一般用于开发调试或测试环节,不建议在生产环境中开启),尽量做到:
    • 开发人员和测试人员都能看懂
    • 通过阅读DEBUG级别的日志后不需要重现问题,就能准确的定位解决问题