cpp-code-checker 1.0.9

C++代码规范检查工具 - 支持命名规范、代码风格和最佳实践检查

C++编程规范检查工具

自动化检查C++代码规范，支持可配置编码规范、白名单过滤和命令行批量检查。

📄 许可证

本项目采用 MIT License 开源许可证。

许可证摘要：

• ✅ 允许商业使用
• ✅ 允许修改
• ✅ 允许分发
• ✅ 允许私人使用
• ⚠️ 需要包含版权声明和许可证文本
• ❌ 不提供任何担保

详细内容请查看 LICENSE 文件。

🚀 快速开始

本项目提供两种使用方式：

1. VS Code 插件（推荐用于日常开发）
2. 命令行工具（推荐用于CI/CD或批量检查）

⚠️ 重要提示

必须在项目根目录运行脚本

# ✅ 正确：在项目根目录运行
cd /path/to/project
python3 code_checker/cpp_checker.py

# ❌ 错误：在code_checker目录运行
cd /path/to/project/code_checker
python3 cpp_checker.py  # 会报错！

🌟 零依赖设计（推荐）

本项目采用零依赖设计，无需安装任何第三方包（无需 pip），只需 Python 3.8+ 标准库即可运行！

离线环境使用：

# Windows
run.bat

# Linux/Mac
./run.sh

# 或通用方式
python run.py -d .

方式1：VS Code 插件（推荐用于日常开发）

安装插件后，在 VS Code 中自动检查 C++ 代码：

安装方法：

1. 在 VS Code 中按 Ctrl+Shift+X 打开扩展市场
2. 搜索 "C++ Code Checker"
3. 点击安装

使用方法：

• 保存文件时自动检查（可配置）
• 按 Ctrl+Shift+C 检查当前文件
• 命令面板中选择 "检查整个工作区"

详细说明请查看：VS Code 插件文档

方式2：命令行工具（推荐用于CI/CD）

Linux/macOS:

# 进入项目根目录
cd /path/to/project

# 检查当前目录
python3 code_checker/cpp_checker.py

# 检查指定目录
python3 code_checker/cpp_checker.py -d /path/to/code

Windows:

# 进入项目根目录
cd D:\path\to\project

# 检查当前目录（推荐使用 run.bat，自动处理中文编码）
run.bat

# 或直接运行 Python
python code_checker\cpp_checker.py

# 检查指定目录
python code_checker\cpp_checker.py -d C:\path\to\code

💡 中文编码提示：

Windows 环境下可能出现中文显示为方框的问题（字符编码问题），解决方法：

方法1：使用 --no-color 参数（推荐）

python code_checker\cpp_checker.py -d . --no-color

方法2：使用 run.bat 脚本（自动处理编码）

run.bat

方法3：输出到文件

python code_checker\cpp_checker.py -d . -o report.txt

方法4：在 PowerShell 中运行（支持 UTF-8）

$env:PYTHONIOENCODING="utf-8"
python code_checker\cpp_checker.py -d .

原因说明：

• 部分旧版 Windows 控制台默认编码为 GBK，不支持 UTF-8
• ANSI 颜色代码在某些 Windows 版本中与中文编码兼容性有问题
• 输出到文件或使用 --no-color 参数可以避免这些问题

🔧 命令行参数

参数	说明	示例
-d, --dir	指定要检查的目录	-d src
-f, --file	检查单个文件	-f main.cpp
-c, --config	指定配置文件路径	-c config/my_standards.json
-w, --whitelist	指定白名单文件路径	-w config/whitelist.json
-o, --output	输出结果到文件（无颜色代码）	-o report.txt
--ignore	忽略的目录（空格分隔）	--ignore build dist
--ext	文件扩展名（空格分隔）	--ext .cpp .h .hpp
--generate-whitelist	生成白名单	--generate-whitelist
--show-filtered	显示白名单过滤数量	--show-filtered
--no-color	禁用颜色输出（Windows中文显示问题解决方案）	--no-color
-h, --help	显示帮助信息	-h

使用示例：

# 检查目录并输出到文件
python3 code_checker/cpp_checker.py -d src -o report.txt

# 检查文件并输出到文件
python3 code_checker/cpp_checker.py -f main.cpp -o result.txt

# 检查目录，忽略 build 和 dist 目录
python3 code_checker/cpp_checker.py -d . --ignore build dist

# 生成白名单
python3 code_checker/cpp_checker.py -d . --generate-whitelist -o whitelist.json

# 使用自定义配置文件
python3 code_checker/cpp_checker.py -d . -c config/my_standards.json -o output.txt

📁 项目结构

├── code_checker/               # 源代码
│   ├── cpp_checker.py          # ✅ C++代码规范检查工具主程序
│   ├── base.py                 # 基础工具类和默认配置
│   ├── config_loader.py        # 配置加载器
│   ├── whitelist.py            # 白名单管理器
│   ├── naming_conventions/     # 命名规范规则模块
│   ├── code_style/             # 代码格式规则模块
│   └── best_practices/         # 最佳实践规则模块
│
├── config/                     # 配置文件
│   ├── coding_standards.json  # 编码规范配置
│   ├── white_list.json        # 白名单配置
│   └── need_check_code_dir.json # 检查目录配置文件
│
├── tests/                       # 测试用例
│   ├── cases/                  # 各种规则的测试用例
│   ├── run_all_tests.py        # 全量测试脚本
│   ├── run_rule_tests.py       # 规则测试脚本
│   └── README.md               # 测试用例说明
│
├── assets/                      # 测试文件
│   ├── test_code_enhanced.cpp
│   ├── usr_test.cpp
│   └── test_class_struct_naming.cpp
│
├── vscode-extension/           # VS Code 插件
│   ├── src/                   # 插件源码
│   ├── python/                # Python检查工具（符号链接）
│   ├── package.json           # 插件配置
│   └── README.md              # 插件说明文档

🔧 依赖说明

本项目采用零依赖设计，无需安装任何第三方包！

依赖	用途	必需
Python 3.8+	运行环境	✅
无第三方包	-	-

⚙️ 配置文件

1. 编码规范配置

文件: config/coding_standards.json

定义19种命名规范和代码格式标准：

• 类名、函数名、变量名的命名规范
• 代码格式（缩进、空格、大括号风格）
• 最佳实践（const正确性、智能指针等）

2. 白名单配置

文件: config/white_list.json

基于符号的白名单，不依赖行号，代码重构后仍然有效。

默认白名单文件：

• config/white_list.json

使用方式：

• 无需命令行指定：工具会自动查找并加载白名单文件
• 指定白名单文件：使用 -w 参数指定自定义白名单

白名单格式：

{
  "class_struct": [],
  "enum_type": [],
  "enum_value": [],
  "function": ["main"],
  "member_function": [],
  "parameter": [],
  "local_variable": [],
  "constant": [],
  "class_member_variable": [],
  "struct_member_variable": [],
  "global_variable": [],
  "static_global_variable": [],
  "macro": [],
  "file_name": [],
  "indentation": [],
  "line_length": [],
  "function_length": [],
  "cyclomatic_complexity": [],
  "no_extern": []
}

命令行使用示例：

# 使用默认白名单文件
python code_checker/cpp_checker.py -f test.cpp

# 指定自定义白名单文件
python code_checker/cpp_checker.py -f test.cpp -w my_whitelist.json

白名单分类说明：

分类	说明	示例
class_struct	类名和结构体名	MyClass, UartDriver
enum_type	枚举类型名	ColorType, LogLevel
enum_value	枚举值	POWER_OFF, COLOR_RED
function	普通函数名	main, printf, FastRead
member_function	成员函数名	calculateSum, getUserInfo
parameter	函数参数名	data, length
local_variable	局部变量名	myVar, temp
constant	常量名	MAX_SIZE, cMaxBufferSize
class_member_variable	类成员变量	_myVar, handle
struct_member_variable	结构体成员变量	myVar, baudRate
global_variable	全局变量名	g_var, g_uartDriver
static_global_variable	静态全局变量名	s_instance, s_count
macro	宏定义	MAX_SIZE, NULL
file_name	文件名	my_file.cpp, test.h

3. 检查目录配置

文件: config/need_check_code_dir.json

配置需要检查的代码目录、忽略列表和文件后缀名。

配置格式：

{
  "_comment": "C++代码规范检查工具配置文件",
  "_usage": "使用命令: python code_checker/cpp_checker.py -d config/need_check_code_dir.json",
  "root": "tests",
  "ignore": [
    "build",
    "dist",
    "venv",
    "__pycache__",
    ".git",
    "node_modules"
  ],
  "extensions": [
    ".cpp",
    ".h",
    ".hpp",
    ".cc",
    ".cxx",
    ".c"
  ]
}

配置项说明：

• root: 检查代码根目录（支持相对路径和绝对路径）
  • 绝对路径：如 "C:\\project\\src" 或 "/home/user/project/src"
  • 相对路径：如 ".", "..", "src"
  • 重要：相对路径是相对于 config 目录（配置文件所在目录）
  • 示例：
    • "." → 检查 config 目录
    • ".." → 检查项目根目录
    • "src" → 检查 config 目录下的 src 目录
• ignore: 需要忽略的文件夹或文件名列表（相对于 root 目录）
• extensions: 需要检查的文件后缀名列表

输出说明： 程序运行时会显示实际的检查路径（绝对路径）：

使用配置文件: config/need_check_code_dir.json
检查目录: /absolute/path/to/check/
忽略目录: build, dist

使用配置文件：

# 使用启动脚本（推荐）
python run.py -d config/need_check_code_dir.json

# 或直接运行主程序
python code_checker/cpp_checker.py -d config/need_check_code_dir.json

📖 使用场景

场景1：日常开发检查

# 不带参数，自动使用默认配置文件检查
python3 code_checker/cpp_checker.py

# 或使用配置文件
python3 code_checker/cpp_checker.py -d config/need_check_code_dir.json

说明：

• 不带 -d 参数时，工具会自动使用 config/need_check_code_dir.json 配置文件
• 可以通过修改该配置文件来调整默认检查行为

场景2：历史代码冻结

对于大量不符合规范的历史代码，使用自动白名单生成：

# 1. 对现有代码进行检查
python3 code_checker/cpp_checker.py -d .

# 2. 生成白名单（冻结历史代码）
python3 code_checker/cpp_checker.py --generate-whitelist

# 3. 使用白名单进行日常检查
# 老代码不受影响，新代码需要遵循规范
python3 code_checker/cpp_checker.py

说明：

• 不带 -d 参数生成白名单时，会自动使用 config/need_check_code_dir.json 配置文件
• 白名单默认生成到 config/white_list.json

场景3：代码审查前严格检查

# 不使用白名单，发现所有问题
python3 code_checker/cpp_checker.py --generate-whitelist

场景4：检查特定目录

# 使用配置文件检查特定目录
python3 code_checker/cpp_checker.py -d config/need_check_code_dir.json

# 或直接指定目录
python3 code_checker/cpp_checker.py -d src

📊 输出示例

控制台输出

🔍 正在检查文件: assets/test_code_enhanced.cpp
============================================================
✅ 检查完成

文件名: test_code_enhanced.cpp
整体评分: 55/100
违规数量: 18
过滤数量: 1

摘要: 代码存在命名规范、格式、内存泄漏和野指针等问题...

📋 命名问题 (6个):
------------------------------------------------------------
  🟡 [行7] 中: 类成员变量x不符合_camelCase命名规范
     💡 建议: 修改为_x
  🟡 [行8] 中: 类成员变量y不符合_camelCase命名规范
     💡 建议: 修改为_y

📋 常见错误 (2个):
------------------------------------------------------------
  🔴 [行40] 高: 内存泄漏：使用new[]分配的数组未释放
     💡 建议: 添加delete[] p;
  🔴 [行50] 高: 野指针：未初始化的指针ptr被解引用
     💡 建议: 初始化指针为nullptr或分配内存后再使用

💾 详细报告已保存: assets/test_code_enhanced.cpp_report.json

JSON报告

{
  "filename": "test_code_enhanced.cpp",
  "overall_score": 55,
  "total_violations": 18,
  "filtered_by_whitelist": 1,
  "analysis_data": {
    "naming_issues": [...],
    "format_issues": [...],
    "common_errors": [...],
    "best_practices": [...]
  }
}

❓ 常见问题

Q1: 本地使用需要什么依赖？

答：本项目采用零依赖设计，无需安装任何第三方包。只需 Python 3.8+ 标准库即可运行。

Q2: 如何使用工具？

有三种使用方式：

1. 使用命令行工具（推荐）：

# 不带参数，自动使用默认配置文件检查
python code_checker/cpp_checker.py

# 检查指定目录
python code_checker/cpp_checker.py -d src

# 检查单个文件
python code_checker/cpp_checker.py -f main.cpp

# 使用配置文件
python code_checker/cpp_checker.py -d config/need_check_code_dir.json

默认行为说明：

• 不带 -d 参数时，工具会自动使用 config/need_check_code_dir.json 配置文件
• 可以通过修改该配置文件来调整默认检查行为（检查目录、忽略列表、文件后缀名）

2. 使用运行脚本：

# Windows
run.bat -d src

# Linux/macOS
./run.sh -d src

Q3: 如何验证环境是否配置正确？

# 测试导入
python3 -c "from code_checker.cpp_checker import CppCodeChecker; print('✓ 导入成功')"

# 测试命令行工具
python3 code_checker/cpp_checker.py --help

Q4: 白名单如何工作？

白名单基于符号名称匹配，不依赖行号：

{
  "class_struct": ["MyClass"],
  "class_member_variable": ["_oldVar"],
  "function": ["main"]
}

符号在白名单中，相关的命名规范问题将被过滤。

默认白名单文件：config/white_list.json

生成白名单：

# 生成白名单到默认位置
python code_checker/cpp_checker.py -d . --generate-whitelist

# 生成白名单到指定位置
python code_checker/cpp_checker.py -d . --generate-whitelist -o my_whitelist.json

Q5: 如何自定义编码规范？

编辑 config/coding_standards.json：

{
  "class_member_variable": {
    "style": "下划线前缀+驼峰命名法",
    "pattern": "^_[a-z][a-zA-Z0-9]*$"
  }
}

Q6: 如何使用配置文件检查代码？

创建或编辑 config/need_check_code_dir.json：

{
  "root": "src",
  "ignore": [
    "build",
    "dist",
    "venv"
  ],
  "extensions": [
    ".cpp",
    ".h",
    ".hpp"
  ]
}

然后使用配置文件检查：

python code_checker/cpp_checker.py -d config/need_check_code_dir.json

Q7: Windows 环境下遇到中文编码错误怎么办？

如果你看到类似 UnicodeEncodeError: 'gbk' codec can't encode character 的错误，可以尝试以下方法：

方法 1: 使用 run.bat（推荐）

run.bat -d src

run.bat 已自动设置 UTF-8 代码页，可以正确处理中文。

方法 2: 直接使用 Python 命令

python code_checker\cpp_checker.py -d src

方法 3: 输出到文件

python code_checker\cpp_checker.py -d src -o report.txt

输出到文件可以避免控制台编码问题。

方法 4: 设置环境变量

set PYTHONIOENCODING=utf-8
python code_checker\cpp_checker.py -d src

Q8: PyPI 安装后如何使用？

如果使用 pip install cpp-code-checker 安装后，可以采用以下方式运行：

方式1：使用模块名（推荐）

# 查看帮助
python -m code_checker --help

# 运行检查
python -m code_checker

# 生成白名单
python -m code_checker --generate-whitelist

方式2：使用命令行工具

# 如果已将 Python Scripts 目录添加到 PATH
cpp-code-checker --help

# 运行检查
cpp-code-checker -f test.cpp

添加 Scripts 目录到 PATH：

1. 打开"系统属性" → "高级" → "环境变量"
2. 在"用户变量"中找到 Path
3. 点击"编辑" → "新建"
4. 添加 Python Scripts 目录（如：C:\Users\你的用户名\AppData\Roaming\Python\Python314\Scripts）
5. 保存并重新打开终端

📚 文档

• 测试用例说明 - 测试用例和规则说明
• VS Code 插件文档 - VS Code 插件使用说明
• PyPI 发布指南 - PyPI 发布指南

🎯 特性

✅ VS Code 插件: 实时代码检查，保存文件时自动检查 ✅ 批量检查: 一次性检查整个项目的所有文件 ✅ 跨平台: 支持Windows、Linux、macOS ✅ UTF-8 支持: 完整支持中文字符，自动处理编码问题 ✅ 可配置: 自定义编码规范和白名单 ✅ 白名单机制: 基于符号，代码重构后仍然有效 ✅ 详细报告: 包含行号、错误类型、修改建议 ✅ 配置文件: 支持使用 JSON 配置文件管理检查参数 ✅ 模块化设计: 每个规则独立为一个模块，易于维护和扩展 ✅ 输出到文件: 支持将检查结果输出到文件，便于归档和分享 ✅ 零依赖: 无需安装第三方包，离线可用

🔌 VS Code 插件

安装

1. 在 VS Code 中按 Ctrl+Shift+X 打开扩展市场
2. 搜索 "C++ Code Checker"
3. 点击安装

使用

快捷键：

• Ctrl+Shift+C - 检查当前文件

命令：

• C++ Code Checker: 检查当前文件
• C++ Code Checker: 检查整个工作区
• C++ Code Checker: 生成白名单

详细说明请查看：VS Code 插件文档

🔗 技术栈

• 语言: Python 3.8+
• 核心依赖: Python 标准库（零第三方依赖）
• 正则表达式: Python re 模块
• 配置文件: JSON 格式
• 数据类: Python dataclasses 模块

📝 许可证

MIT License

🤝 支持

如有问题，请参考文档或联系开发团队。