作者 | 不可说
出品 | 汽车电子与软件
MAB规范，即Model-Based Design Across MathWorks Products建模规范，是MathWorks公司制定的用于提高MATLAB和Simulink模型可读性、可维护性和可重用性的标准。
在汽车电子行业的MBD开发过程中，通常会要求符合MAB规范。
MAB规范中的各项规则都是有固定的ID，规则ID是用于标识指南的唯一标识符，它由两个小写字母和一个四位数字组成，这两部分之间通过下划线分隔。例如，规则ID的格式可以是“xx_nnnn”。一旦分配，规则ID便是永久性的，不会发生变化。这样的设计确保了每个规则ID都能准确且唯一地代表其对应的指南。
MAB规范涉及命名约定、Simulink、Stateflow等多个方面，本文将基于V6版本的规范介绍下各种模块的命名约定规则，并给出一定的实践建议。
#02
命名约定分为两大类：
1. 一般命名约定（General Conventions）这部分规定了在不同情境下（如变量、函数、文件等）命名时应遵循的一般性原则。这些原则旨在确保命名的清晰性、一致性和易于理解，从而提高代码的可读性和可维护性。
2. 内容命名约定（Content Conventions），这部分则更具体地针对特定类型的内容（如文档、数据库表、字段等）规定了命名规则。这些规则旨在确保内容的组织结构清晰，命名准确反映内容的本质，从而便于信息的查找、理解和使用。
通过遵循这些命名约定，开发团队可以确保项目中的命名规范统一，减少命名冲突和误解，提高团队协作效率和代码质量。
#03
这部分含有四条规则：
规则：
a) 文件名中应仅使用以下字符类型：
单字节英文字母（a-z, A-Z）；
单字节数字（0-9）；
单字节下划线（_）；
不得使用换行符、单字节空格、双字节字符和控制字符。（控制字符：ASCII码小于32的字符（如换行符、制表符等））；
b) 文件名不得以数字开头。
c) 文件名不得以下划线开头。
d) 文件名不得以下划线结尾。
e) 文件名中不得出现连续的下划线。
f) 文件名不得仅为单个MATLAB保留字。
g) 在MATLAB路径中的文件名不得重复。
这些规范旨在确保文件名的清晰性、一致性和唯一性，从而便于文件的识别、管理和访问。遵循这些规范可以提高代码的可读性和可维护性，减少潜在的命名冲突和误解。
错误示例：
同名文件将保存到MATLAB路径的文件夹中。
规则
a) 文件夹名称中仅允许使用以下字符类型：
单字节字母数字字符（a-z、A-Z、0-9）；
单字节下划线（_）；
不允许使用换行符、单字节空格、双字节字符和控制字符。
b) 文件夹名称不能以数字开头。
c) 文件夹名称不能以下划线开头。
d) 文件夹名称不能以下划线结尾。
e) 文件夹名称中不能使用连续的下划线。
f) 文件夹名称不能仅由 MATLAB 的单个保留字组成。
错误示例：
文件夹使用了MATLAB保留字/文件夹名称以数字开头了；
实践建议：
不使用空格：建议用下划线（_）或连字符（-）代替空格。
保持简洁：文件夹名称应简短且具有描述性，避免使用过长或复杂的名称。
统一命名规则：在项目中采用一致的命名规则，以提高可读性和可维护性。
规则：
a) 模型文件名长度不得超过63个字符（不包括点和扩展名）。
模型引用可能无法引用过长的文件名。
规则：
a) 文件夹名称长度不得超过63个字符。
过长的文件夹名称可能导致完整路径名无法在用户界面中显示。
#04
这部分含有十六条规则：
这三条的规则基本一致，放这里一起讲
规则：
a) 结构化子系统/块/Inport和Outport块名称中仅允许使用以下字符类型：
单字节字母数字字符（a-z, A-Z, 0-9）；
单字节下划线（_）；
不允许使用换行符、单字节空格、双字节字符和控制字符。
b) 子系统/块/Inport和Outport块名称不能以数字开头。
c) 子系统/块/Inport和Outport块名称不能以下划线开头。
d) 子系统/块/Inport和Outport块名称不能以下划线结尾。
e) 子系统/块/Inport和Outport块名称中不能使用连续的下划线。
f) 子系统/块/Inport和Outport块名称不能仅由 MATLAB 的单个保留字组成。
有额外的说明如下：
在添加新的块名称时，不允许使用换行符和单字节空格。然而，当这些字符最初被用作保存在Simulink库中的块名称时，它们是允许的。双字节字符和控制字符则不应使用。
比如下面的示例就是正常的：
子系统的错误示例：
块的错误示例：
Inport和Outport块错误示例：
实践建议
统一命名规范
比如对于Inport和Outport块来讲，使用一致的命名规范，例如In_SignalName或Out_SignalName，这有助于快速识别输入和输出信号。
避免保留字
不要使用 MATLAB 的保留字作为 Inport或Outport 块的名称，例如 in, out, input, output 等，这可能会导致代码生成或模型解析时出现问题。
清晰的命名
使用有意义的名称来描述信号的内容或来源，例如In_Temperature 或 Out_Speed，而不是简单的In1或Out1，这有助于快速理解信号的含义。
这三条的规则一致，放这里一起讲：
规则：
a) 结构化子系统名称的长度不得超过63个字符。
实践建议：
1. 简洁命名
尽量使用简洁明了的名称来描述子系统的功能，避免过长的名称。例如，使用 SpeedControlSubsystem而不是 SpeedControlSystemForVehicleManagementSubsystem。
2. 避免不必要的描述
避免在子系统名称中包含不必要的描述性文字。例如，SubsystemForProcessingData可以简化为DataProcessingSubsystem。
3. 使用缩写
对于较长的名称，可以使用合理的缩写来保持在长度限制内，但要确保缩写在项目团队中是通用且易于理解的。例如，VehicleControlSubsystem可以缩写为VehCtrlSubsystem。
4. 分层命名
如果子系统具有层次结构，可以在名称中使用下划线来分隔层次，但要注意总长度不超过限制。例如，Level1_SubsystemName。
规则：
a) 信号和总线名称中仅允许使用以下字符类型：
单字节字母数字字符（a-z, A-Z, 0-9）
单字节下划线（_）
不允许使用换行符、单字节空格、双字节字符和控制字符。
b) 信号和总线名称不能以数字开头。
c) 信号或总线名称不能以下划线开头。
d) 信号和总线名称不能以下划线结尾。
e) 信号和总线名称中不能使用连续的下划线。
f) 信号和总线名称不能仅由 MATLAB 的单个保留字组成。
实践建议：
1.统一命名规范
对于信号和总线，使用一致的命名规范，例如SignalName 或BusName，这有助于快速识别信号和总线的功能。
2.清晰的命名
使用有意义的名称来描述信号或总线的内容或功能，例如TemperatureSignal或ControlBus，而不是简单的Sig1或Bus1，这有助于快速理解信号或总线的含义
规则：
a) 参数名称不能以下划线结尾。
b) 参数名称中不能使用连续的下划线。
c) 参数名称不能仅由 MATLAB 的单个保留字组成。
实践建议：
避免下划线的误用
避免在参数名称中以下划线结尾或使用连续的下划线，这可能会导致可读性问题或与某些工具的命名规则冲突。
避免保留字
不要使用MATLAB的保留字作为参数名称，例如if,for,while等，这可能会导致代码生成或模型解析时出现问题。
清晰的命名
使用有意义的名称来描述参数的用途，例如GainValue或ThresholdLevel，而不是简单的 param1或param2，这有助于快速理解参数的含义。
统一命名规范
在项目中统一使用字母、数字和下划线来命名参数，避免使用特殊字符或空格，这有助于提高模型的可读性和一致性。
这三条的规则一致：
a) 信号总线/参数/Stateflow数据名称的长度不得超过63个字符。
虽然没有明确的最小长度限制，但建议名称至少包含一个字符以保持可读性。
实践建议：
1. 简洁命名：
尽量使用简洁的名称来描述信号和总线，避免冗长的名称。例如，使用 SpeedSignal 而不是 VehicleSpeedSignalForEngineControl。
2. 层次化命名：
如果需要更详细的描述，可以使用层次化的命名方式，例如Eng.Speed（表示发动机速度）或Ctrl.Bus（表示控制总线）。这样可以在不超出长度限制的情况下提供足够的信息。
3. 避免不必要的前缀或后缀：
避免在信号和总线名称中添加不必要的前缀或后缀，除非它们对于理解信号的含义是必要的。例如，避免使用Sig_SignalName或Bus_BusName，除非它们有助于区分不同的信号或总线。
4. 统一命名规范：
在项目中统一参数名称的命名规范，例如使用驼峰命名法（CamelCase）或下划线分隔（snake_case），以提高可读性和一致性。
规则：
a) Stateflow数据名称不能以下划线开头。
b) Stateflow数据名称不能以下划线结尾。
c) Stateflow数据名称中不能使用连续的下划线。
d) Stateflow数据名称不能仅由MATLAB的单个保留字组成。
规则：
a) 在基础工作区和模型工作区中，数据名称定义不得重复。
b) 数据名称在基础工作区和数据字典（sldd）中不得重复定义。
c) 数据名称在模型工作区和数据字典（sldd）中不得重复定义。
实践建议：
统一管理数据定义：
在项目中使用数据字典（sldd）来集中管理数据定义，避免在不同工作区中重复定义相同的数据名称。
明确命名规范：
制定清晰的数据命名规范，确保数据名称具有唯一性和描述性。例如，使用前缀或后缀来区分不同来源或用途的数据。
避免全局变量冲突：
在定义全局变量时，确保其名称在模型的所有工作区中都是唯一的，避免因重复定义导致的意外行为。
使用工具检查重复定义：
使用Simulink的Model Advisor检查工具来验证模型中的数据名称是否重复定义，确保数据名称的唯一性。
规则：
a) 数据字典（sldd）中仅定义在 Simulink 或 Stateflow Coder 模型中实际使用的数据。
b) 模型工作区中仅定义在 Simulink 或 Stateflow 模型中实际使用的数据。
实践建议：
定期清理：
定期检查和清理数据字典和模型工作区，移除未使用的数据定义。这有助于减少模型的复杂性，提高模型的可维护性。
明确需求：
在定义数据时，确保每个数据项都有明确的用途。如果某个数据项在模型中没有被引用，应考虑将其删除。
使用工具辅助：
利用Simulink提供的工具（如Model Advisor）来检测未使用的数据。这些工具可以自动识别并报告未使用的数据项。
版本控制：
在进行数据清理之前，确保对模型进行版本控制备份。这可以防止意外删除重要数据。
规则：
a) 配置参数“未使用的数据”应设置为“警告”或“错误”，以防止在Stateflow块中出现未使用的Stateflow数据、事件和消息。
在Stateflow模块中，未使用的数据和事件可能会影响代码的可维护性和可重用性。具体来说，当在生成的代码中插入关于未使用数据的声明性语句时，这些未使用的数据和事件会对代码产生影响。
正确示例：
错误示例：
实践建议：
定期清理未使用数据：
在开发过程中，定期检查并清理未使用的Stateflow数据、事件和消息，以保持模型的整洁和高效。
启用警告或错误提示：
在项目设置中，将“未使用的数据”配置参数设置为“警告”或“错误”，以便在模型中出现未使用数据时能够及时发现并处理。
代码生成前的检查：
在生成代码之前，确保所有未使用的数据都已被清理，以避免在生成的代码中出现不必要的声明，这可能会增加代码的复杂性和维护成本。
规则：
a) 应避免使用保留的C语言变量名作为变量名。举例来说，诸如const、TRUE、FALSE、infinity、nil、double、single或enum等C语言中的保留字，在MATLAB编程时应予以避免，以防止潜在的命名冲突或误解。
b) 应避免使用与MATLAB内置函数相冲突的变量名。例如，conv是MATLAB中的一个函数，用于执行卷积运算，因此，不应将conv用作变量名，以防止覆盖或混淆MATLAB的内置功能。为了保持代码的清晰性和可维护性，建议选择与MATLAB函数名不冲突的变量名。
通过这种要求，可以提高代码的可读性：这使得代码更加清晰易懂，便于维护和调试。
#05
MAB规范中对命名约定做出的规范具有重要的意义：
1. 提高代码的可读性和可维护性
统一标准：通过定义明确的命名规则，确保所有开发人员遵循相同的命名标准，减少因命名不一致导致的混淆。
清晰表达意图：规范的命名能够清晰地表达变量、信号、模块或参数的用途和功能，使代码更易于理解。
降低维护成本：统一的命名规则使得代码更易于维护和修改，尤其是在团队协作或长期项目中。
2. 避免命名冲突和错误
防止保留字冲突：通过限制使用系统或工具的保留字，避免因命名冲突导致的编译错误或运行时异常。
减少歧义：明确的命名规则可以减少因命名歧义导致的逻辑错误或误解。
3. 增强跨平台和跨工具的兼容性
工具兼容性：MAB规范考虑了不同工具（如MATLAB、Simulink）的命名限制，确保命名规则适用于多种开发环境。
跨平台一致性：规范的命名规则可以确保代码在不同平台（如Windows、Linux）上的兼容性，避免因平台差异导致的命名问题。
通过遵循这些规范，开发人员可以显著提升代码质量，降低开发成本，并确保项目的高效推进。
