4. MATLAB编码规范与可维护性

在工程算法开发中，MATLAB 代码往往从几十行的验证脚本起步，最终演化为数千行、多人协作、需要长期维护的算法库。决定这段演化是否可控的，不是算法本身有多巧妙，而是编码规范是否被稳定执行。规范的价值在于降低“阅读成本”和“修改风险”：当命名、函数边界、注释和分层方式保持一致时，任何一位工程师都能在几分钟内定位到需要改动的代码，并判断改动会影响哪些调用方。

命名规则：让名字承载类型与语义

MATLAB 的弱类型特性使命名成为最重要的自文档手段。建议遵循以下约定：变量使用小写字母加下划线（snr_db、frame_len），避免使用 i、j 作为普通循环变量以外的含义，因为它们在 MATLAB 中默认表示虚数单位；常量使用全大写加下划线（MAX_ITER、FS_HZ）；函数名使用小写驼峰或下划线，动词开头，如 calcEvm、loadWaveform；类名使用大驼峰，如 OfdmModulator。单位应写入名字，例如 fc_hz 比 fc 更明确，delay_samp 比 delay 更少歧义。

需要特别避免的是“临时名扩散”：tmp、data1、a、b 一旦进入被复用的函数，就会成为后续维护的隐患。一个可执行的判断标准是：如果变量在函数返回后仍被其他代码引用，它的名字必须能说明物理含义或数据结构含义。

函数组织：单一职责与清晰接口

函数是 MATLAB 模块化的基本单元。一个函数应只完成一件可命名的事，输入输出数量尽量控制在 3～4 个以内。当参数增多时，应使用结构体或 arguments 块组织，例如：

function y = applyFilter(x, opts)
    arguments
        x double
        opts.Fs (1,1) double = 1e6
        opts.Order (1,1) double {mustBePositive} = 64
        opts.Method (1,:) char = 'fir'
    end
    ...
end

arguments 块同时承担了默认值、类型校验和接口文档三重职责，比在函数体内写大量 if nargin < 3 更清晰，也更容易被 IDE 和测试框架识别。函数文件应遵循“一个主函数 + 若干局部函数”的结构，局部函数放在主函数之后，避免在脚本中定义大量匿名函数导致调用栈难以追踪。

注释标准：解释“为什么”而非“做什么”

MATLAB 的 help 和 doc 命令直接读取函数头部注释，因此头部注释必须包含：函数用途一句话、输入参数说明、输出说明、典型调用示例。函数体内注释应解释设计决策、边界条件来源和算法依据，而不是复述代码。例如 % 计算均值 没有价值，而 % 使用滑动平均抑制突发噪声，窗口长度取 16 以匹配帧结构 才提供了代码之外的信息。

对于算法中的关键公式，建议在注释中写明出处或推导前提，例如 % 按 3GPP TS 38.211 第 5.3 节生成 DMRS 序列。当参数取值来自实测或标定时，应注明来源和适用范围，避免后续人员误改。

代码分层与模块化设计原则

工程算法代码通常可分为四层：接口层负责参数解析、单位转换和输入校验；算法层实现核心计算，不依赖具体文件路径或硬件；数据层负责读写、缓存和格式转换；验证层包含测试脚本、参考数据和断言。分层的核心原则是“依赖单向”：接口层可以调用算法层和数据层，算法层不应反向调用接口层，也不应直接读写文件。这样算法层才能被单独测试和复用。

模块化设计还应遵循“高内聚、低耦合”：同一模块内的函数共享同一数据结构，模块之间通过明确的输入输出结构体通信，而不是通过 global 或 assignin 共享变量。对于需要跨模块传递的配置，建议定义一个配置结构体，由接口层统一构造后传入。

上图给出了分层与依赖方向的一个典型示例。接口层向下调用算法层和数据层，验证层以测试方式调用算法层，而算法层保持“纯计算”属性，不反向依赖任何上层或外部资源。这种单向依赖使算法层可以在没有文件系统和硬件的情况下被完整测试。

可维护性的落地检查

规范是否真正落地，可以通过几个可观察的信号判断：新成员能否在不询问原作者的情况下找到某个算法的入口；修改一个参数后，能否通过搜索确定所有受影响的位置；运行测试时，算法层是否能在不加载数据文件的情况下通过。若这些问题的答案是否定的，说明命名、分层或注释中至少有一项没有执行到位。

最后需要强调的是，规范的目的不是限制表达，而是让代码在时间维度上保持可读、可改、可验证。命名让意图可见，函数组织让职责清晰，注释让决策可追溯，分层让依赖可控。四者共同作用，才能把一次性的算法验证脚本转化为可长期维护的工程资产。