云梦环境项目主要旨在用于学术以及实验用途,因此在设计各种算法和方案的实现细节时,编码的清晰度是重中之重。
尽管如此,它的所有数值和算法在很多方面都与面向工业的 CFD 代码相似。
欢迎各位开发者参与云梦环境项目的开发,有以下几种方式可以参与:
如果你对云梦环境项目感兴趣,想参与到项目的开发中来,可以先阅读开发者指南了解项目的开发流程,然后在项目仓库中提交你的代码。
如果你在使用云梦环境项目过程中遇到问题,或者有好的建议,欢迎在项目仓库中提交issues或者discussions。
如果你对云梦环境项目有更深入的理解,或者想参与到项目的讨论中来,欢迎在项目仓库中提交discussions。
如果你对云梦环境项目有更深入的理解,或者想参与到项目的文档编写中来,欢迎在项目仓库中提交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 风格指南,主要追求:
一致性:遵循统一的编码风格,使得代码易于阅读和理解。
易读性:代码应该易于理解,易于维护。
代码注释
我们完全不介意你的注释是代码的2倍、3倍 …,你的代码、你的成果,你想说什么、想说多少都可以。
日志
良好的系统,可以通过日志进行问题定为。除了在本地代码上复现、调试外,还要能够通过丰富合理的日志信息还原问题现场,发现错误位置和原因。
为什么打日志
什么时候该打日志?
日志分级
ERROR。该级别日志发生时,已经影响了用户的正常使用,通常程序抛错、中止。主要类型有:
WARN。该级别日志不应该出现但是不影响程序继续运行的问题。主要类型有:
INFO。该级别日志主要用于记录系统运行状态、等信息,常用于反馈系统当前状态给用户。主要类型有:
DEBUG。该级别日志的主要作用是对系统每一步的运行状态进行精确的记录。(该级别的日志一般用于开发调试或测试环节,不建议在生产环境中开启),尽量做到: