一份简单实用的MATLAB M语言编码风格指南

MATLAB M语言编码风格指南

- - 1. 文件命名
  - 2. 函数命名
  - 3. 注释
  - 4. 变量命名
  - 5. 布局、注释和文档
  - 6. 代码结构
  - 7. 错误处理
  - 8. 性能优化
  - 9. 格式化输出

MATLAB M文件的编码规范对于确保代码的可读性、可维护性和一致性非常重要。下面是一份MATLAB M语言编码规范的建议，可以作为参考：

1. 文件命名

使用小写字母和下划线分隔单词（如 my_function_name.m）。
描述性命名，清楚地表达文件功能。

2. 函数命名

遵循文件命名规则，同时保持函数名与文件名一致。
避免使用MATLAB内置函数名作为自定义函数名。

3. 注释

开头文档块：每个M文件开始处都应该有一个描述性的注释块，包括函数用途、输入输出参数说明、作者、日期等。见下方实例
内联注释：在复杂的代码段前或后添加注释，解释其目的或逻辑。
持续更新注释：当修改代码时，相应更新注释。

%MY_FUNCTION_NAME Example function to demonstrate the use of an H1 line and help text.
%MY_FUNCTION_NAME(X) takes input X and returns the result of some operation.
%
%   Input:
%       X - A numeric vector or matrix
%
%   Output:
%       Y - The output vector or matrix after applying the operation
%
% Example usage:
%   Y = my_function_name([1 2 3; 4 5 6]);
%
% Author: Vincent
% Date: July 24, 2024
% Version: 1.0function Y = my_function_name(X)% Function body starts here...

4. 变量命名

变量名应该以小写字母开头的大小写混合形式，譬如：shadowFadingTable
意义明确：变量名应反映其内容，如 numSamples。
避免使用单个字母作为变量名，除非它们具有广泛认可的意义（如 i, j 用于循环）。
区分大小写：MATLAB是大小写敏感的，确保一致性。
迭代器变量应以 i、j、k 等命名或前缀，如iFiles, jColumns
避免使用否定的布尔变量名，例如使用 isFound 而非 isNotFound
首字母缩略词即使通常为大写，也应混合或小写，如html, isUsaSpecific

5. 布局、注释和文档

使用缩进来提高代码层次结构的可见性，通常每个层级增加四个空格。
操作符两侧使用空格（如 a = b + c）。
内容应保留在前 80 列内。
应在逗号、空格和运算符之后分割行。
续行与上一行表达式的开头对齐，例如：

totalSum = a + b + c ... d + e;

6. 代码结构

使用模块化：将大型任务分解成多个小函数。
避免全局变量：尽可能使用局部变量和函数参数。

7. 错误处理

使用try-catch结构来捕获和处理异常。
清晰的错误消息：当抛出错误时，提供详细的错误信息。

function dotProduct = safeDotProduct(v1, v2)% SAFE_DOTPRODUCT Computes the dot product of two vectors safely.%   DOTPRODUCT = SAFE_DOTPRODUCT(V1, V2) computes the dot product of two%   vectors V1 and V2. If the vectors do not have the same length, it throws%   an error.%%   Input:%       v1 - First vector (numeric array)%       v2 - Second vector (numeric array)%%   Output:%       dotProduct - Dot product of the vectors (numeric scalar)tryif ~isequal(size(v1), size(v2))error('Vectors must have the same length.');enddotProduct = dot(v1, v2);catch MEfprintf('Error: %s\n', ME.message);dotProduct = NaN; % 或者可以返回一个特定的错误代码end
end

8. 性能优化

向量化：尽量使用向量化操作而不是循环，从底层实现来看，向量操作本质也是循环遍历，但MATLAB的内部对向量操作有进行优化，通常比循环更快。
举例：计算一个向量中所有元素的平方和

    sumSquares = 0;for i = 1:length(v)sumSquares = sumSquares + v(i)^2; % Not recommendedendsumSquares = sum(v.^2); % Recommended

预分配数组：在循环前预分配数组以减少内存重分配。
推荐方式：

% 预分配数组
n = 1000000; % 数组最终大小
A = zeros(1, n); % 预分配数组
for i = 1:nA(i) = i; % 直接赋值，无需重新分配内存
end

不推荐方式

% 不预分配数组
n = 1000000; % 数组最终大小
A = zeros(1, 0); % 初始化为空数组
for i = 1:nA(end+1) = i; % 每次迭代增加一个元素
end

9. 格式化输出

使用fprintf或其他适当的输出函数，保持输出的清晰和一致性。

function print_results(a, b, c)% PRINT_RESULTS Prints results with formatted output.%   PRINT_RESULTS(A, B, C) prints the values of A, B, and C in a specific format.%%   Input:%       a - First value (numeric scalar)%       b - Second value (numeric scalar)%       c - Third value (numeric scalar)fprintf('The values are: A = %.2f, B = %.2f, C = %.2f\n', a, b, c);
end