OpenFOAM-6 C++ 编码风格指南详解

前言

作为一款开源的计算流体力学(CFD)软件，OpenFOAM的代码风格一致性对于项目的可维护性和可读性至关重要。本文将详细解读OpenFOAM-6中的C++编码规范，帮助开发者编写符合项目标准的代码。

基础代码规范

基本格式要求

1. 行长度限制：每行代码不超过80个字符
2. 缩进规则：
   • 使用4个空格作为一级缩进
   • 禁止使用Tab键缩进
3. 空白字符：避免行尾出现多余空格

控制结构规范

// 正确的if语句格式
if (condition)
{
    code;
}

// 长条件可以这样写
if
(
    long condition
)
{
    code;
}

注意：if和(之间必须有一个空格

流输出对齐

// 正确的流输出对齐方式
Info<< ...
os  << ...

// 警告信息的正确格式
WarningInFunction
    << "Warning message"

文件组织规范

头文件(.H)规范

1. 类声明格式：

/*---------------------------------------------------------------------------*\
                        Class exampleClass Declaration
\*---------------------------------------------------------------------------*/

2. Doxygen注释：

//- 函数简要描述
//  详细描述可以跨多行
//  使用//-开头的注释会被Doxygen识别
thing function(stuff1, stuff2);

3. 列表注释：

//- 比较triFaces
//  返回值:
//  -  0: 不同
//  - +1: 相同
//  - -1: 相同面但方向不同
static inline int compare(const triFace&, const triFace&);

源文件(.C)规范

1. 命名空间使用：

// 正确的方式：完全限定函数名
Foam::returnType Foam::className::functionName()

// 例外情况：多级命名空间可以展开
namespace Foam
{
namespace compressible
{
namespace RASModels
{
    ...
}
}
}

2. 函数间距：函数之间保留两个空行

编码实践建议

参数传递原则

• 基本类型(bool, label, scalar等)通过值传递
• 较大对象通过引用传递
• 尽可能使用const修饰符

变量初始化

// 推荐方式
const className& variableName = otherClass.data();

// 不推荐方式
const className& variableName(otherClass.data());

虚函数规范

如果基类中有虚函数，所有派生类中的对应函数都应声明为virtual

循环结构规范

基本循环

// for循环标准格式
for (i = 0; i < maxI; i++)
{
    code;
}

// 长条件可以这样写
for
(
    i = 0;
    i < maxI;
    i++
)
{
    code;
}

OpenFOAM特有循环宏

// 正确的forAll格式
forAll(

// 错误的格式
forAll (

注意：当迭代对象包含逗号时，这些宏可能会失败

代码换行规范

函数声明换行

// 正确的换行方式
const Foam::longReturnTypeName&
Foam::longClassName::longFunctionName const

// 更长的函数名可以再次换行
const Foam::longReturnTypeName&
Foam::veryveryveryverylongClassName::
veryveryveryverylongFunctionName const

赋值语句换行

// 正确的赋值换行
variableName =
    longClassName.longFunctionName(longArgument);

// 多参数情况
variableName =
    longClassName.longFunctionName
    (
        longArgument1,
        longArgument2
    );

数学与逻辑表达式

运算符间距

a + b, a - b      // 加减法两边有空格
a*b, a/b          // 乘除法无空格
a & b, a ^ b      // 位运算符两边有空格
a = b, a != b     // 赋值和比较运算符两边有空格
a < b, a > b      // 比较运算符两边有空格
a || b, a && b    // 逻辑运算符两边有空格

长表达式换行

// 数学表达式换行
variableName =
    a*(a + b)
   *exp(c/d)
   *(k + t);

// 更清晰的方式
variableName =
(
    a*(a + b)
   *exp(c/d)
   *(k + t)
);

// 逻辑表达式换行
if
(
    a == true
 && b == c
)

文档注释规范

基本结构

Class
    Foam::myClass

Description
    类的简要描述。

    类的详细描述可以跨越多行，
    提供更全面的说明。

代码示例

Description
    实现文件的读写操作。

    示例输入文件:
    \verbatim
        patchName
        {
            type        patchType;
            refValue    100;
            value       uniform 1;
        }
    \endverbatim

    实现中的循环示例:
    \code
        forAll(patches, patchi)
        {
            ...  // 一些操作
        }
    \endcode

参考文献格式

使用APA格式书写参考文献：

Description
    标准k-epsilon湍流模型。

    Reference:
    \verbatim
        Launder, B. E., & Spalding, D. B. (1972).
        Lectures in mathematical models of turbulence.
    \endverbatim

拼写与术语规范

1. 优先使用英式拼写，如"neighbour"而非"neighbor"
2. 方法名推荐使用"-ize"结尾，如"initialize()"
3. 保持术语在整个项目中的一致性

结语

遵循OpenFOAM的编码风格指南不仅能提高代码的可读性和可维护性，还能确保项目的一致性。本文涵盖了从基本格式到高级文档规范的各个方面，希望能帮助开发者编写出符合OpenFOAM标准的优质代码。