matlab 编程之代码规范

矫情吗；* 2023-02-17 01:16 22阅读 0赞

# 一、标识符命名原则 #

> 标识符的名字应当直观，其长度应当符合“最小长度，最大信息量”原则

## 1、非矩阵变量 ##

*  变量名应该以小写字母开头的大小写混合形式 譬如：`shadowFadingTable`，`servingSector`， `rxBufferForRe userID`，`userPriorityProfile`，`mcsOneRetrieval`等。
 *  循环变量应该以 `i` 、`j` 、`k` 等为前缀，如
    
        for  i_File = 1：nFiles 
            for  j_Position = 1：nPositions

*  避免仅用最后的字母s(表示单复数)区别两个变量, 例如`point`和`points`. 可以用类似`pointArray`的形式加以区别。
 *  避免使用一个关键字或者特殊意义的字作为变量名
 *  结构体的命名应该以一个大写字母开头，结构体的命名应该是暗示性的，并且不需要包括字段名（fieldname）应采用`Segment.length`，避免用`Segment.SegmentLength`

## 2、常数 ##

*  命名常数（包括全局变量）应该采用大写字母，用下划线分割单词，如`MAX_ITERATIONS`，`COLOR_RED`
 *  参数可以以某些通用类型名作为前缀，如`COLOR_RED`，`COLOR_GREEN`

## 3、草稿变量，含矩阵，结构体，元胞 ##

*  应用范围比较大的变量应该具有有意义的变量名，作为“`草稿变量`”的的临时存储空间或者索引可以用短名字。程序员在读到这样的变量的时候，可以假定这个变量的值在没有几行之后的代码中就不会再用到。通常的“草稿变量”整数的时候用 `i`，`j` ，`k` ，`m` ，`n`（最好少用i，j，因为他们作为MATLAB中的永久性常量表示虚数单位的）。双精度数的时候常用 `x`，`y` 和 `z` 。`m` 表示矩阵，没有 `m` 表示标量
 *  命名上将`cell`, `struct` 与MATLAB中最常见的 `numeric array` ，即数值矩阵区分开来.
 *  `n` 用于整数变量, 如`n_File`.
 *  `m`用于一般的矩阵，如`matrix_channelHFResponse`;
 *  `c`用于`cell array`, 如`cell_temp= cell(1, 4)`;
 *  `s`用于 `struct array`， 如 `stuct_user= struct('field', {})` ;
 *  `matrix`，`cell`，`stuct`后面的`channelHFResponse`， `user`用来表示有特定含义的中间变量，比如`matrix_channelHFResponse`，用来表示计算`channelHFResponse`时中间变量。

## 4、函数 ##

*  函数名应该采用小写字母，函数名应该是具有意义的，下划线分割单词  
    如采用： `compute_total_width（）`避免`compwid（）`
 *  前缀`get/set` 应该作为访问对象或者属性的保留前缀，如`getobj（.）`。
 *  前缀`compute`应该用在计算某些量的函数的地方`computespread（）`。
 *  前缀 `is`应该用在布尔函数的命名的地方，如 `iscomplete（）`。
 *  `Find`，`initialize`类似。

# 二、编码及文档注释要求及实例 #

## 1、代码版式 ##

M文件函数说明

function [ 函数输出参数] =  函数名( 函数输入 )
    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    %此处为函数名，如果不是函数文件就取消此行 
    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    %创建人： 
            %日  期： 
        	%修改人： 
        	%日  期： 
        	%函数变量及功能的简单描述 
    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    --函数主体

编码设计

> 本部分说明了M文件编码的设计，包括以下几个方面：垂直间隔，水平间隔，缩进与对齐，注释。

垂直间隔

> 空行起着分割块或段落的作用，块（段落）之间一般留一个或两个空行。

*  空行使用规则
    
     *  逻辑块之间要留空行
     *  结构体定义之间要留空行
     *  函数定义体之间要留空行
     *  函数体内，完整的控制结构和单独的语句块之间要留空行
     *  逻辑上密切相关的语句序列之间不要留空行
 *  换行注意事项
    
     *  不在一行使用多个语句。唯一的例外是for语句。For语句的初始化，条件和循环都可以在一行中。例如：
        
            for (bcnl_num = 0; bcnl_num < count; bcnl_num++)

或者还有switch语句，如果动作很短并且相同的话（后面有详细描述）。If语句并不是例外：执行语句总是另起一行。例如：

`if (bcnl_num > count) bcnl_num = count;`

*  ｛｝与case总是独占一行

水平间隔

*  逗号后面要有空格，但是不要在结构的成员与指针操作符前后有空格。例如：`foo.index`

在 `=`，`&&`，`+`，`-`，`>`, `<`与 `||` 前后加上空格，包括`：`如

simpleAverage = (firstTerm + secondTerm) / two;
    1 : nIterations

*  另起一行时，后面一行和前面一行中要继续的地方对齐:

weithedPopulation = (doctorWeight * nDoctors) +...
      				  (layerWeight * nLawyers) + ... 
      				  (chiefWeight * nChiefs)；...
    function (param1，param2，...
      		param3)

长行拆分

> 一行代码不能超过180个字符。长行拆分时，在逻辑断点处分行。拆分时，运算符放在被拆分行的尾部，而不是新行的首部。拆分后的新行应与被拆分行采用能够表现出逻辑关系的对齐方式。

*  示例：

if (((new_shape.x > left_border) &&
       (new_shape.x < right_border)) &&
      ( (new_shape.y > bottom_border) &&
       (new_shape.y < top_border))) {
    	draw(new_shape);
    }

代码行及行内空格

*  代码行中不运行出现中文。
 *  关键字后要留空格。像`const`、`inline`、`case`等关键字后要留空格，以辨析关键字；像`if`、`fo`、`do`、`while`、`switch`等关键字后要留空格再跟左括号`（`，以突出关键字。
 *  `（` 若不在一行的开始，应与前面的字符空格。例如，`if`、`while`、`do-while`、`switch`、`for`语句等控制结构块的`（`应与这些关键字语句之间空格。
 *  `,`之后要留空格；若`；`不是一行的结束符，后面也要留空格。
 *  `？`、`：`前后都要留空格。
 *  `（`、`[`向后紧跟，`]`、`，`、`；`、`）`向前紧跟，紧跟处不留空格。
 *  一元运算符与所作用的操作数之间不要加空格，如`！`、`～`、`++`、`&`、`*`等。
 *  `.`、`->`这类运算符前后都不要留空格。

缩进与对齐

*  缩进的水平是一个TAB键，可将编辑器的TAB符定义为4个空格。
 *  嵌套块之间使用4个空格（一个TAB键）的缩进方式。
 *  模块和子程序头以及子程序声明从第一列起。
 *  下列情况下缩进一个水平：
    
     *  子程序声明
     *  条件（看下面）
     *  循环的结构
     *  switch语句
     *  case labels
 *  条件的else与if有相同的缩进。因此格式就是：

fid = fopen（fileName）； 
    if（fid~ = -1） 
    	statements 
    else 
    	statements
    end

*  switch语句的一般格式：

switch（condition） 
    	case    ABC 
    		处理语句； 
    	case    DEF 
    		处理语句； 
    	otherwise 
    		处理语句； 
    end

*  注释与它们作注释的代码部分有相同的缩进（见Comments）。

注释

*  程序内部不同功能模块要空一行，同时附注释说明模块的作用、功能。这样程序结构清晰易懂，便于同学间学习交流。

例如：

*      %% 注释说明下模块一的功能
               ...模块一...代码...
              此处为空行
        %% 注释说明下模块二的功能
              	...模块二...代码...
 *  多层循环嵌套要在每一个结束的end 后加注释说明该层循环结束

例:

for            %循环1
        for             %循环2
            for            %循环3
                ......
                 代码段
                ......
            end            %循环3结束
        end            %循环2结束

end %循环1结束  
\`\`\`

*  用于理解一小段代码含义的注释，统一写在代码上方，如
    
        %（1）初始化 
        Number = zeros(1,PNumber);             %Number存放每个工件的工序数，PNumber工件个数 
        for i = 1:PNumber 
            Number(i) = MNumber;               %MNumber工序个数 
        end
    
     *  用于理解一句代码的意思可以写在代码后方，但是注意不能超过180字符。太长可以考虑写在代码上方
 *      gen = 0;  %迭代计数器 
        JmNumber = Max_Cell(Jm);               %调用Max_Cell子函数求机器的数量 
        [PNumber,MNumber] = size(Jm);          %PNumber为工件个数，MNumber为工序个数 
        trace = zeros(2,MAXGEN);               %寻优结果的初始值，一行存放各代的最优解，一行存放各代解的均值 
        TotalOP_Number = PNumber*MNumber;      %工序总个数
 *  大段代码，有完整的阶段性的运行结果，需要使用%% 形式，使用单元来注释
    
        %% 子函数程序13：Find函数
        function  Pos = Find(FindVal,S) 
        [m,n] = size(S); 
        Pos = -1; 
        for i = 1:n  
            if FindVal == S(i) 
              Pos = i; 
              break; 
            end 
        end

# 参考： #

[MATLAB 代码规范][MATLAB]

[MATLAB]: https://www.cnblogs.com/gshang/p/10919989.html