文章

C++文件组织规范模板

C++ 文件组织规范模板包括头文件声明接口和类，源文件实现逻辑，使用命名空间隔离模块，静态变量在 .cpp 中定义，保持结构清晰、职责分明。

发表于
作者 Sylvan
4 分钟阅读
C++文件组织规范模板

C++ 文件组织规范模板

文件结构示例

1
2
3
4

math/
├── math.h         // 对外暴露的接口
├── math.cpp       // 接口的实现
├── math_internal.h // 私有辅助函数声明（可选）

.h 文件（对外接口）

作用

  • 声明对外可见的函数、类、常量
  • 不包含实现细节（除模板或 inline 函数）

格式模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

#ifndef MATH_H
#define MATH_H

#include <vector>
#include <string>

namespace math {

// 常量定义
constexpr double PI = 3.141592653589793;

// 普通函数声明
int add(int a, int b);
double average(const std::vector<int>& nums);

// 类声明示范
class Calculator {
public:
    Calculator();
    explicit Calculator(const std::string& owner);

    ~Calculator();

    int add(int a, int b) const;
    double average(const std::vector<int>& nums) const;

    void setOwner(const std::string& owner);
    std::string getOwner() const;

    static int getInstanceCount();

private:
    std::string owner_;
    static int instanceCount_;

    // 私有辅助函数（只在类内部使用）
    void updateState();
};

} // namespace math

#endif // MATH_H

.cpp 文件（接口实现）

格式模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

#include "math.h"

namespace math {

// 静态成员变量初始化
int Calculator::instanceCount_ = 0;

// 普通函数实现
int add(int a, int b) {
    return a + b;
}

double average(const std::vector<int>& nums) {
    if (nums.empty()) return 0.0;
    int sum = 0;
    for (int n : nums) sum += n;
    return static_cast<double>(sum) / nums.size();
}

// 类成员函数实现

Calculator::Calculator() : owner_("Unknown") {
    ++instanceCount_;
}

Calculator::Calculator(const std::string& owner) : owner_(owner) {
    ++instanceCount_;
}

Calculator::~Calculator() {
    --instanceCount_;
}

int Calculator::add(int a, int b) const {
    return a + b;
}

double Calculator::average(const std::vector<int>& nums) const {
    if (nums.empty()) return 0.0;
    int sum = 0;
    for (int n : nums) sum += n;
    return static_cast<double>(sum) / nums.size();
}

void Calculator::setOwner(const std::string& owner) {
    owner_ = owner;
    updateState();
}

std::string Calculator::getOwner() const {
    return owner_;
}

int Calculator::getInstanceCount() {
    return instanceCount_;
}

void Calculator::updateState() {
    // 私有函数具体实现
}

} // namespace math

.h 内部头文件（可选）

场景：模块内部共用、外部不暴露的函数或工具

1
2
3
4
5
6
7
8
9
10
11

// math_internal.h
#ifndef MATH_INTERNAL_H
#define MATH_INTERNAL_H

namespace math {
    static int clamp(int x, int low, int high) {
        return (x < low) ? low : (x > high ? high : x);
    }
}

#endif

注意：这种 static 函数若出现在头文件中，每个包含它的 .cpp 文件都会生成一份副本。若为工具函数，可考虑 inline 替代。

命名和修饰符规范

元素类型推荐修饰符写在 .h 还是 .cpp
普通函数无（或 extern）.h 中声明，.cpp 中定义
内部函数static 或匿名命名空间.cpp 中定义
内联函数inline.h 中定义
模板函数无（只能写 .h）.h 中定义
类 / 枚举推荐放 .h.h 中定义

小建议

  • .h 文件总是要写 include guard 或 #pragma once
  • 尽量用命名空间包裹函数 / 类，防止污染全局空间
  • 拆分职责清晰的模块，函数不宜太长
  • .cpp 文件中优先包含对应 .h，可防止头文件漏包含依赖
  • 使用 clang-format 等工具保持风格一致
cpp, cpp basics
CPP
本文由作者按照 CC BY 4.0 进行授权