RuView代码规范指南：构建高质量WiFi感知系统的编码实践

核心理念：规范背后的设计思想

在RuView项目中，代码规范不仅仅是格式要求，更是确保WiFi信号处理、姿态估计算法和实时跟踪系统可靠性的基础保障。本指南基于"可读性优先、一致性为基、场景适配"三大原则，帮助开发者在复杂的无线感知系统开发中保持代码质量。

理解代码规范的价值

RuView作为基于WiFi的人体姿态估计系统，其代码质量直接影响信号处理精度和系统稳定性。良好的代码规范能够：

• 提高协作效率：统一的代码风格减少团队沟通成本
• 降低维护难度：清晰的结构使后期功能扩展更简单
• 提升系统可靠性：规范的错误处理和测试确保关键算法稳定运行
• 加速问题定位：一致的日志记录和命名约定简化调试过程

WiFi-DensePose系统架构展示了从原始WiFi信号到姿态估计结果的完整流程，良好的代码组织是实现这一复杂系统的基础

规范设计的核心原则

1. 领域驱动：规范设计需考虑WiFi感知领域的特殊性
2. 实用性优先：避免为规范而规范，关注实际开发效率
3. 渐进式改进：支持现有代码库的平滑迁移
4. 自动化保障：尽可能通过工具实现规范检查

实践框架：从基础到场景化应用

构建模块化代码组织

基础规范

• 必须：采用领域驱动的目录结构，按功能模块划分代码
• 必须：每个模块遵循单一职责原则，专注于特定功能
• 建议：模块间通过明确定义的接口交互，减少直接依赖
• 避免：跨模块循环依赖和过度紧耦合

场景案例：大型功能开发

在开发多AP协同感知功能时，合理的模块划分至关重要：

src/
├── sensing/              # 核心感知功能
│   ├── csi_processing/   # CSI信号处理
│   ├── multi_ap/         # 多AP协同逻辑
│   └── pose_estimation/  # 姿态估计算法
├── api/                  # 对外接口
└── hardware/             # 硬件适配层

这种结构确保每个功能点都有明确归属，新加入的开发者能快速定位相关代码。

常见误区

• 将所有功能塞进单一模块，导致"大泥球"式代码
• 过度拆分模块，增加不必要的跨模块调用开销
• 忽视模块间接口设计，导致频繁重构

规范自检清单

• [ ] 每个模块是否专注于单一功能领域？
• [ ] 模块间依赖是否清晰且单向？
• [ ] 新功能是否自然融入现有模块结构？
• [ ] 是否避免了跨模块的常量和配置共享？

实现一致的命名体系

基础规范

• 必须：类名使用PascalCase（每个单词首字母大写的骆驼命名方式）
• 必须：函数和变量使用snake_case（全小写，单词间用下划线连接）
• 必须：常量使用全大写SNAKE_CASE
• 建议：变量名体现具体含义而非类型（如signal_strength而非float_value）
• 避免：使用模糊的缩写和单字母变量（除常见约定如i、j用于循环）

场景案例：跨语言命名对比

不同语言在RuView项目中的命名实践：

语言	类/结构体	函数/方法	变量	常量
Python	CSIProcessor	process_frame()	signal_strength	MAX_SAMPLE_RATE
Rust	CsiProcessor	process_frame()	signal_strength	MAX_SAMPLE_RATE
JavaScript	CsiProcessor	processFrame()	signalStrength	MAX_SAMPLE_RATE

常见误区

• 混合使用不同命名风格，如csiProcessor（错误）与CsiProcessor（正确）
• 使用技术术语而非业务术语命名，如fft_data而非frequency_spectrum
• 命名过于冗长或过于简短，失去可读性

规范自检清单

• [ ] 是否所有类名使用PascalCase且准确描述其职责？
• [ ] 函数名是否采用动词开头，清晰表达其功能？
• [ ] 变量名是否包含足够上下文，避免歧义？
• [ ] 常量是否全部大写并放在合适的作用域？

编写可靠的错误处理代码

基础规范

• 必须：定义层次化的自定义异常体系
• 必须：捕获特定异常而非通用Exception
• 建议：使用结构化日志记录异常上下文
• 建议：为用户提供可操作的错误信息
• 避免：静默忽略异常或仅打印而不抛出

场景案例：CSI数据处理异常处理

# 错误示范
def process_csi_data(data):
    try:
        # 处理逻辑
        return result
    except:
        print("Error processing data")
        return None

# 优化过程
def process_csi_data(data):
    try:
        # 处理逻辑
        return result
    except ValueError as e:
        logger.error(f"Invalid CSI data format: {e}")
        raise
    except Exception as e:
        logger.exception("Unexpected error processing CSI data")
        raise

# 正确实践
class CSIProcessingError(WiFiDensePoseError):
    """CSI数据处理相关错误"""
    pass

def process_csi_data(data: CSIData) -> ProcessedData:
    """处理CSI数据并返回处理结果
    
    参数:
        data: 原始CSI数据对象
        
    返回:
        处理后的CSI特征数据
        
    异常:
        CSIProcessingError: 当数据验证失败或处理出错时
    """
    try:
        validate_csi_data(data)
        result = extract_features(data)
        logger.debug(f"Processed CSI data with {len(result)} features")
        return result
    except ValidationError as e:
        raise CSIProcessingError(f"Data validation failed: {e}") from e
    except FeatureExtractionError as e:
        raise CSIProcessingError(f"Feature extraction failed: {e}") from e

常见误区

• 使用通用异常捕获掩盖真实错误
• 不记录异常堆栈信息，难以调试
• 抛出过于泛化的异常，增加调用方处理难度
• 错误信息不包含足够上下文，无法定位问题

规范自检清单

• [ ] 是否为不同错误场景定义了特定异常？
• [ ] 异常是否包含有意义的错误消息和上下文？
• [ ] 是否正确使用raise ... from保留异常链？
• [ ] 异常是否在适当层级处理或向上传递？

设计高性能类型系统

基础规范

• 必须：为所有公共API提供完整类型注解
• 建议：使用不可变数据结构表示核心领域对象
• 建议：对复杂数据模型使用Pydantic或dataclasses
• 避免：过度使用Any类型或动态类型转换

场景案例：多语言类型定义对比

RuView中CSI数据点的类型定义：

# Python
from dataclasses import dataclass
from typing import List, Optional

@dataclass(frozen=True)
class CSIDataPoint:
    """CSI数据点包含振幅和相位信息"""
    amplitude: float
    phase: float
    timestamp: float
    subcarrier_index: Optional[int] = None
    
    def is_valid(self) -> bool:
        return 0 <= self.amplitude <= 1 and -3.14 <= self.phase <= 3.14

// Rust
#[derive(Debug, Clone, PartialEq)]
pub struct CsiDataPoint {
    pub amplitude: f32,
    pub phase: f32,
    pub timestamp: f64,
    pub subcarrier_index: Option<u32>,
}

impl CsiDataPoint {
    pub fn is_valid(&self) -> bool {
        self.amplitude >= 0.0 && self.amplitude <= 1.0 && 
        self.phase >= -std::f32::consts::PI && self.phase <= std::f32::consts::PI
    }
}

// TypeScript
interface CSIDataPoint {
    amplitude: number;
    phase: number;
    timestamp: number;
    subcarrierIndex?: number;
}

function isValidDataPoint(point: CSIDataPoint): boolean {
    return point.amplitude >= 0 && point.amplitude <= 1 &&
           point.phase >= -Math.PI && point.phase <= Math.PI;
}

常见误区

• 忽略类型注解，降低代码可读性和IDE支持
• 过度复杂的类型层次，增加理解难度
• 不验证数据有效性，导致下游处理错误
• 频繁类型转换，影响性能和可靠性

规范自检清单

• [ ] 是否所有公共接口都有完整的类型注解？
• [ ] 核心数据结构是否不可变？
• [ ] 是否定义了数据验证方法？
• [ ] 复杂类型是否有清晰的文档说明？

建立跨团队协作规范

基础规范

• 必须：遵循Conventional Commits提交消息规范
• 必须：每个Pull Request关联至少一个Issue
• 建议：代码审查关注逻辑正确性而非风格问题
• 建议：通过自动化工具确保基础规范合规
• 避免：大型无拆分的Pull Request

场景案例：紧急修复流程

当生产环境出现CSI信号处理异常时，遵循以下流程：

1. 创建hotfix/csi-processing-crash分支
2. 提交修复时使用fix(csi): resolve null pointer in phase sanitization格式
3. PR描述中引用相关Issue和错误报告
4. 至少一位团队成员审查并批准
5. 所有自动化测试通过后合并
6. 合并后立即创建发布标签

常见误区

• 提交消息不规范，难以跟踪变更目的
• PR过大难以审查，增加合并风险
• 缺乏测试覆盖，修复引入新问题
• 沟通不足导致重复工作或冲突

规范自检清单

• [ ] 提交消息是否遵循Conventional Commits格式？
• [ ] PR是否聚焦单一功能或修复？
• [ ] 是否包含适当的测试覆盖？
• [ ] 文档是否同步更新？

进阶技巧：处理复杂场景与优化

遗留代码改造指南

基础规范

• 必须：在修改遗留代码时遵循"最小侵入"原则
• 必须：为修改的遗留代码添加测试覆盖
• 建议：采用"strangler pattern"逐步替换旧代码
• 建议：优先重构高风险、高频率修改的代码
• 避免：一次性大规模重构

场景案例：Python到Rust的模块迁移

RuView项目中CSI处理模块从Python迁移到Rust的过程：

1. 创建Rust crate wifi-densepose-signal实现核心算法
2. 编写Python绑定层，保持原有Python API
3. 在测试环境验证功能一致性
4. 逐步切换生产环境流量
5. 移除旧Python实现

不同实现方式的性能对比，展示了规范重构和语言优化带来的改进

常见误区

• 忽视旧代码的业务逻辑细节，导致功能回归
• 没有充分测试就替换关键模块
• 过度追求完美设计，延误交付
• 不保留旧代码的兼容性接口

规范自检清单

• [ ] 是否理解旧代码的所有功能和边界情况？
• [ ] 迁移/重构是否有完整的测试覆盖？
• [ ] 是否制定了回滚计划？
• [ ] 新实现是否与系统其他部分兼容？

规范冲突解决方案

性能优化与代码可读性

当性能优化需求与代码可读性冲突时：

1. 首先编写清晰可读的代码
2. 通过性能测试识别瓶颈
3. 仅对已证实的性能热点进行优化
4. 优化代码必须添加详细注释说明原因
5. 保留未优化版本作为注释或文档参考

# 可读性优先的实现
def calculate_rssi(signals):
    """计算平均RSSI值"""
    return sum(signal.strength for signal in signals) / len(signals)

# 性能优化版本（当数据量超过10000条时）
def calculate_rssi(signals):
    """计算平均RSSI值（优化版本）
    
    优化说明：直接操作内部数组而非对象属性，
    在100万样本下性能提升约40%
    """
    sum_strength = 0.0
    count = 0
    for signal in signals:
        sum_strength += signal[3]  # 直接访问数组索引而非属性
        count += 1
    return sum_strength / count

快速迭代与代码质量

在紧急功能开发时：

1. 明确标记临时解决方案（使用TODO或FIXME）
2. 记录技术债务并添加到Issue跟踪系统
3. 确保基本测试覆盖，即使是简单的冒烟测试
4. 计划后续迭代中的重构和优化
5. 在团队内部明确临时代码的边界和风险

规范自检清单

• [ ] 性能优化是否有数据支持？
• [ ] 临时解决方案是否有明确标记和跟踪？
• [ ] 是否在不影响功能的前提下保持代码质量？
• [ ] 团队是否对规范冲突的解决方案达成共识？

附录：规范速查表与自动化工具

核心规范速查表

Python代码规范

• 缩进：4个空格，不使用制表符
• 行长度：88个字符
• 导入顺序：标准库 → 第三方库 → 项目内部
• 命名：PascalCase（类），snake_case（函数/变量），全大写（常量）
• 类型：为所有公共函数提供类型注解

Rust代码规范

• 缩进：4个空格
• 命名：PascalCase（结构体/枚举），snake_case（函数/变量），SCREAMING_SNAKE_CASE（常量）
• 文档：为公共API提供文档注释（///）
• 错误处理：使用Result类型，避免恐慌（panic!）

JavaScript/TypeScript代码规范

• 缩进：2个空格
• 命名：PascalCase（类），camelCase（函数/变量），UPPER_CASE_SNAKE_CASE（常量）
• 分号：使用分号结束语句
• 类型：TypeScript中为所有接口和公共函数提供类型定义

自动化检查工具配置

Python工具链

# 安装工具
pip install black flake8 mypy isort

# 配置文件示例 (pyproject.toml)
[tool.black]
line-length = 88
target-version = ['py38', 'py39', 'py310']
exclude = '''
/(
    \.git
  | \.mypy_cache
  | \.venv
)/
'''

[tool.isort]
profile = "black"
multi_line_output = 3

Rust工具链

# 安装工具
cargo install rustfmt clippy

# 配置文件示例 (rustfmt.toml)
max_width = 100
hard_tabs = false
newline_style = "Auto"

提交检查

# 安装pre-commit钩子
pip install pre-commit

# 配置文件 (.pre-commit-config.yaml)
repos:
  - repo: https://github.com/psf/black
    rev: 22.10.0
    hooks:
      - id: black
  - repo: https://github.com/PyCQA/flake8
    rev: 6.0.0
    hooks:
      - id: flake8

项目文档与资源

• 完整API文档：docs/api-reference.md
• 架构设计文档：docs/architecture-overview.md
• 贡献指南：docs/developer/contributing.md
• 测试指南：docs/developer/testing-guide.md

通过遵循这些规范和实践，RuView项目能够保持代码质量，提高开发效率，并确保WiFi感知系统的可靠性和性能。记住，规范是帮助我们构建更好系统的工具，而非束缚创新的枷锁。随着项目的发展，规范本身也应定期回顾和改进，以适应新的需求和挑战。