MATLAB代码编写标准

hyowinner

MATLAB 编码标准

该文件包含 MATLAB 开发的综合编码标准。在生成 MATLAB 代码以及审查代码质量和标准合规性时，请使用这些规则。

许可证

本作品根据 Creative Commons Attribution 4.0 International License 获得许可。

命名指南通用命名原则

• 当编写的代码可能被母语与您不同的人阅读或使用时，对 MATLAB 标识符使用共同语言，例如英语。
• 对于编程接口的元素，包括函数、类和方法，优先使用精确且描述性的名称。除非含义显而易见，否则不要为函数或方法使用短名称。
• 尽可能避免在编程接口元素的名称中使用缩写词。使用完整单词。仅使用无歧义、在组织或领域内常用或易于从上下文中确定的缩写。
• 避免使用 MATLAB 路径上现有函数或类的名称来命名变量、函数和类。名称冲突可能导致"遮蔽"，这可能会产生意外或不一致的行为。
  
  

变量

• 限制变量名长度不超过 32 个字符。
• 优先使用描述性的变量名。当变量的含义可以很容易地从其使用上下文中确定时，允许使用短变量名。
• 短变量名允许用于以下情况：
  • 数学表达式。
  • 短小的连续代码块。
  • 循环中的临时变量或迭代器。
  • 特定领域用户广泛熟知的值（数学：phi = 黄金比例，物理：h = 普朗克常数）。
    
    
• 不要混合使用变量的单数和复数形式（例如，point 和 points）。考虑使用后缀来表示复数。
• 避免使用否定形式的变量名，如 isNot 或 notFound。
• 对于由多个单词组成的描述性变量名，使用 lowerCamelCase。
• 对于诸如常见数学符号等短变量名，可以使用首字母大写。
  
  

函数与方法

• 限制名称长度不超过 32 个字符。
• 使用动词或动词短语命名函数和方法，以传达执行的操作。
• 或者，如果名词描述了所创建的事物，可以使用名词或名词短语命名函数和方法。
• 在转换函数的名称中使用数字 "2"（例如，struct2table）。
• 对于主要输出为逻辑值的函数，使用前缀 "is" 或 "has"。
• 为具有互补操作的函数使用互补的名称（例如，start/stop，create/destroy）。
• 函数名称使用 lowerCamelCase 或全部小写。对于组合多个单词的函数名，优先使用 lowerCamelCase。
• 方法名称应遵循与函数名称相同的原则，使用动词短语或名词短语。
• 方法名称使用 lowerCamelCase 或全部小写。对于组合多个单词的方法名，优先使用 lowerCamelCase。
  
  

名称-值参数

• 在名称-值参数中使用 UpperCamelCase。
  
  

类

• 如果一个类表示一个事物，使用名词或名词短语作为名称（例如，PrintServer）。
• 如果一个类实现了一系列行为或能力，其他类可以通过继承获得这些行为或能力，例如 mixin 类，则使用形容词（例如，Copyable）。
• 不要在类名中包含 "class"。
• 不要在名称中使用类的特殊属性（例如，Abstract）。
• 对于在命名空间中定义的类，使用 UpperCamelCase。
• 如果类是在 MATLAB 全局命名空间中定义的，则使用上述函数名称的大小写规则。
  
  

属性、事件和命名空间

• 大多数属性名使用名词或名词短语。
• 如果属性是一个逻辑值，指示对象是否执行、能够执行或拥有某些东西，则使用动词短语（例如，HasOutputPort）。
• 属性名使用 UpperCamelCase。
• 事件名使用 UpperCamelCase。
• 命名空间使用简短的小写名称。
• 不要在函数、类、枚举或内部命名空间的名称中使用命名空间名称。
  
  

语句与表达式指南通用语句

• 不要将多个语句放在同一行。
• 避免在表达式中使用字面值，尤其是当这些值出现在多个地方时。同样，避免在函数调用中使用字面值。在这两种情况下，使用变量代替。
• 浮点字面量应写成小数点前带有数字（例如，"0"）。
  
  

变量与数据

• 避免使用全局变量。相反，应将变量作为参数传递给函数。
• 尽量减少持久变量的使用。在函数调用之间将数据缓存在持久变量中，可用于避免每次函数调用都重新加载或重新计算大量数据。
• 在一个代码块中定义结构体的所有字段。不要在其创建函数之外向现有结构体添加或删除字段。
• 仅当存储不同类和/或大小的数据时使用元胞数组。不要使用元胞数组存储作为文本数据的字符向量。改用字符串数组。
  
  

语法与运算符

• 不要在函数或方法中使用命令语法。命令语法的使用应仅限于命令行或脚本中。
• 在数学和逻辑表达式中使用括号以提高可读性。
• 不要使用 == 或 ~= 来比较两个浮点值。
• 使用 fileparts、fullfile 和 filesep 函数以平台无关的方式创建或解析文件名。
  
  

控制流

• 将循环和条件语句的嵌套限制在 5 层。
• 避免在循环内增量式地更改数组的大小。尽可能在循环之前立即预分配数组。
• 不要在 for 循环内修改循环迭代器。
• 尽量减少在 for 或 while 循环内使用 break、continue 和 return。仅当 break 和 continue 能使循环更简洁或更易读时才使用它们。
• 使用 if-else 时，将常见情况放在 if 部分，将例外情况放在 else 部分。
• switch 语句应始终包含一个 otherwise 块。如果 otherwise 块为空，则包含一条注释，解释为什么不会出现其他情况。
  
  

函数调用

• 调用无参函数或类方法时使用空括号。这将清楚地表明正在使用的是函数而不是变量。合理的例外包括某些常见函数，如 pi、true 和 false，以及某些图形相关函数，如 gcf 和 gca。
• 使用波浪号字符 (~) 忽略函数未使用的第一个输出。
• 在向函数传递名称-值参数时，使用 Name=Value 语法 (R2021a)。
  
  

应避免的函数

• 避免使用 eval 函数。eval 函数可能导致意外的代码执行，尤其是在将函数与不受信任的用户输入一起使用时。
• 避免使用在当前上下文之外操作工作区的函数。不应使用 evalin 和 assignin 函数作为函数输出的替代品。不应将基础工作区中的变量当作全局变量使用。
• 尽量减少在函数或方法中使用 cd、addpath 和 rmpath 来修改当前文件夹或 MATLAB 搜索路径。如果必须使用这些函数，请在退出函数前重置当前文件夹和路径。
  
  

格式化指南空格

• 使用空格而非制表符来添加空白。
• 每个缩进级别使用 4 个空格。
• 不要在左括号、左方括号或左花括号后立即添加空格。
• 不要在右括号、右方括号或右花括号前立即添加空格。
• 在逗号或分号后添加空格，行尾除外。
• 不要在行尾添加额外的空白。
  
  

运算符

• 在赋值语句的赋值运算符 (=) 两侧各使用一个空格。
• 当使用 Name=Value 语法指定函数的可选参数时，不要在 = 周围使用空格。
• 在关系运算符 (<、<=、==、~=、>、>=) 的两侧各使用一个空格。
• 在逻辑运算符 (&、&&、|、||) 的两侧各使用一个空格。
• 不要在三元运算符 : 周围或其两侧的操作数之间使用空格。
• 不要在乘、除或幂运算符 (* .* / ./ \ .\ ^ .^) 周围放置空格。
• 当表达式出现在赋值语句的右侧时，在对该表达式主要项进行运算的加号和减号运算符周围使用空格。在其它位置不要使用空格，例如在分组项内、作为函数参数或作为索引操作数。
• 不要在一元运算符 +、- 或 ~ 后使用空格。
  
  

空行

• 使用一个空行分隔执行不同任务或逻辑上相关的代码段。
• 使用一个空行分隔局部函数声明。
• 使用一个空行分隔 classdef 文件中的方法声明。
• 使用一个空行分隔 classdef 文件中的方法块。
• 使用一个空行分隔 classdef 文件中的属性块。
• 不要在脚本、函数或 classdef 文件的顶部或底部添加额外的空行。
  
  

行长度与换行

• 代码和注释行的长度不应超过 120 个字符。
• 拆分长行以最大化可读性。当需要换行时，考虑在逗号、空格或二元运算符之后进行换行。
  
  

代码注释指南通用注释

• 当编写的代码可能被母语与您不同的人阅读或使用时，对代码中的注释使用共同语言，例如英语。
• 在注释符号 % 后至少使用一个空格。
• 使用 %% 定义新的代码节。
  
  

函数文档

• 将函数的 H1 行放在函数声明之后、arguments 块之前。
• H1 行应提供函数功能的简要描述。
• 跟在 H1 行之后的帮助文本应提供用户使用函数所需的信息，包括语法、输入和输出的描述以及任何副作用。
  
  

注释位置

• 注释应放在其所要解释的代码之前。
• 简短的注释可以放在行尾。
  
  

缩进

• 使用与函数声明相同的缩进级别缩进函数开头的 H1 和帮助行。
• 否则，将注释行缩进到与其紧随其后的代码行相同的级别。
  
  

函数编写指南文件组织

• 函数文件名应与顶层函数的名称相同。
• 所有函数均以 end 关键字结尾。
• 仅被另一个函数或脚本使用的函数应作为局部函数写在同一个文件中。
• 保持局部函数简单。如果一个函数需要独立测试，请将其放在自己的文件中。
  
  

函数结构

• 更改 MATLAB 全局或系统状态时请务必小心。在函数或方法退出时恢复状态。如果未将修改的状态重置为原始值，后续代码可能会运行异常。
• 限制嵌套函数的使用。嵌套函数几乎总是可以用局部函数替代。
• 保持匿名函数简单易读。尽可能将匿名函数的定义和使用放在一起。
• 不要在函数中重复代码块。将这些语句重构为一个新的函数或局部函数。
  
  

函数参数

• 将函数声明中的输入参数数量限制为 6 个。对于可选信息，使用名称-值参数。多个名称-值参数可以在函数声明中表示为单个参数。
• 对于旨在作为外部、面向用户的编程接口一部分的函数，需验证其输入参数。使用 arguments 块进行验证。
• 避免使用 varargin 处理名称-值参数。应使用带有可选参数和名称/值对的 arguments 块。
• 编写逐元素函数时，确保它们能适用于任何数组形状。与特定形状输入对应的输出应具有相同的形状。
  
  

函数输出

• 将函数声明中的输出参数数量限制为 4 个。
• 不要因为输出参数数量的变化而改变某个输出的含义。
• 在函数声明中使用逗号分隔输出参数。
  
  

类编写指南类文件与结构

• classdef 文件名应与类的名称相同。
• 相对于句柄类，优先使用值类。
• 使用句柄类来表示其状态可以在不改变其身份的情况下更改的对象。
• 考虑对以下情况的类使用句柄：
  • 表示物理或唯一对象，如硬件设备或文件。
  • 表示可见对象，如图形组件。
  • 在关系数据结构（如列表或树）中定义对象。
    
    
  
  

类属性

• 如果您不希望其他人将您的类用作超类，请使用 Sealed 类属性。仅当该类设计为可被其他人扩展时，才保持类未密封 (Sealed)。
• 避免使用具有相同属性的多个属性块，除非它们用于对相关的类属性进行逻辑分组。
• 避免使用具有相同属性的多个方法块，除非它们用于对相关的类方法进行逻辑分组。
  
  

属性

• 在满足类用户需求的前提下，尽可能限制属性的访问权限。这可以使类的设计更容易随时间演进。例如，仅当属性需要被类的用户设置时，才允许设置访问。
• 避免仅为了验证而使用设置方法（set methods）。应使用属性验证语法。如果遇到需要验证并转换属性的情况，使用设置方法可能更高效。
• 仅在以下一种或多种情况为真时使用依赖属性（Dependent）：
  • 其值仅根据其他属性的值计算得出。
  • 兼容性要求该属性必须对类的用户可用，即使该属性已不再用于实现中。
  • 属性更改需要对其他属性产生副作用。
    
    
• 否则，使用非依赖属性。
  
  

方法

• 对于旨在作为外部、面向用户的编程接口一部分的方法（公共方法），需验证其输入参数。使用 R2019b 引入的 arguments 块进行验证。
• 避免编写返回多个参数的类构造函数。类构造函数必须返回类的一个有效对象或对象数组。
• 除非方法是设计供类的用户调用的，否则将其设为私有或受保护。
• 避免对非依赖属性使用获取方法（get methods）。
• 在创建具有自定义索引的类时，使用模块化索引。尽可能避免重载 subsref 和 subsasgn。
  
  

错误处理指南代码质量

• 在将代码提交到源代码管理或将代码提供给他人使用之前，修复所有代码分析器警告。
  
  

错误消息

• 编写能提供具体信息的错误消息，以帮助用户理解问题并知道如何处理。
• 错误消息应采用以下三种形式之一：
  • 问题与解决方案形式：消息的第一句说明问题。下一句解释解决方法。
  • 解决方案形式：错误消息是一个陈述，说明用户可以做什么或必须满足什么条件才能解决问题。
  • 问题形式：错误消息是一个陈述。当无法说明针对问题的具体解决方案时使用。
    
    
  
  

异常处理

• 在处理错误时，将全局状态或设置重置为其原始值。考虑使用 try-catch 块或 onCleanup 对象来重置状态。
• 使用 try-catch 块进行错误处理或处理特殊条件。
• 不要将 try-catch 用于正常的流程控制。
• 每个 try 块都配有一个对应的 catch 块。如果 catch 块为空，请包含一条注释，解释为什么不需要进一步处理。
• 当 catch 块尝试从特定错误中恢复时，使用 MException 对象。不要假设发生了哪个错误。
• 避免使用 throwAsCaller。
  
  

附加指南字符串处理

• 使用双引号 " 代替单引号 ' 来表示字符串，除非必须使用单引号。
  
  

属性访问

• 使用 obj.PropertyName 代替 get/set 方法来访问属性，除非在处理对象数组时这种方式过于不便。