This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

Guideline Template

Guideline descriptions are documented, using the following template. Companies that want to create additional guidelines are encouraged to use the same template.

ID: TitleXX_nnnn: Title of the guideline (unique, short)
PriorityMandatory, Strongly recommended, or Recommended
ScopeMAAB, NA-MAAB, J-MAAB, Specific Company (for optional local company usage)
MATLAB® VersionsOne of the following:
All
RX, RY, RZ
RX and earlier
RX and later
RX through RY
PrerequisitesLinks to guidelines, which are prerequisites to this guideline (ID: Title)
DescriptionDescription of the guideline (text, images)
RationaleMotivation for the guideline
Last
Change
Version number of last change
Model
Advisor
Check
Title of and link to the corresponding Model Advisor check, if a check exists

Note

The elements of this template are the minimum required items for understanding and exchanging guidelines. You can add project or vendor fields to this template as long as their meaning does not overlap with existing fields. Such additions are encouraged if they help to integrate other guideline templates and lead to a wider acceptance of the core template.

Guideline ID

  • The guideline ID is built out of two lowercase letters (representing the origin of the rule) and a four-digit number, separated by an underscore.

  • Once a new guideline has an ID, the ID does not change.

  • The ID is used for references to guidelines.

  • The two letter prefixes na, jp, jc and eu are reserved for future MAAB committee rules.

  • Legacy prefixes, db, jm, hd, and ar, are reserved. The MAAB committee will not use these prefixes for new rules.

  • No new rules are to be written with these legacy prefixes.

Guideline Title

  • The title should be a short, but unique description of the guidelines area of application (for example, length of names)

  • The title is used for the Prerequisites field and for custom checker tools.

  • The title text should appear with a hyperlink that links to the guideline.

Note

The title should not be a redundant short description of the guidelines content, because while the latter may change over time, the title should remain stable.

Priority

Each guideline must be rated with one of the following priorities:

  • Mandatory

  • Strongly recommended

  • Recommended

The priority describes the importance of the guideline and determines the consequences of violations.

MandatoryStrongly Recommended Recommended
Definition

Guidelines that all companies agree to that are absolutely essential.

Guidelines that all companies conform to 100%.

Guidelines that are agreed upon to be a good practice, but legacy models preclude a company from conforming to the guideline 100%.

Models should conform to these guidelines to the greatest extent possible; however, 100% compliance is not required.

Guidelines that are recommended to improve the appearance of the model diagram, but are not critical to running the model.

Guidelines where conformance is preferred, but not required.

Consequences: If the guideline is violated,

Essential items are missing.

The model might not work properly.

The quality and appearance deteriorates

There may be an adverse effect on maintainability, portability, and reusability

The appearance does not conform with other projects.

Waiver Policy: If the guideline is intentionally ignored,

The reasons must be documented.

  

Scope

The scope of a guideline may be set to one of the following:

ScopeDescription
MAAB (MathWorks® Automotive Advisory Board)A group of automotive manufacturers and suppliers that work closely together with MathWorks. MAAB includes the subgroups J-MAAB and NA-MAAB.
JMAAB (Japan MAAB)A subgroup of MAAB that includes automotive manufacturers and suppliers in Japan and works closely with MathWorks. Rules with J-MAAB scope are local to Japan.
NA-MAAB (North American MAAB)A subgroup of MAAB that includes automotive manufacturers and suppliers in the United States and Europe and works closely with MathWorks. Rules with NA-MAAB scope are local to the United States and Europe.

MATLAB Versions

The guidelines support all versions of the MATLAB and Simulink® products. If the rule applies to specific versions, the versions are identified in the MATLAB versions field. The version information is in one of the following formats.

Format Definition
AllAll versions of MATLAB
RX, RY, or RZ A specific version of MATLAB
RX and earlier Versions of MATLAB until version RX
RX and laterVersions of MATLAB from version RX to the current version
RX through RYVersions of MATLAB between RX and RY

Prerequisites

  • The Prerequisite field is for links to other guidelines that are prerequisites for this guideline (logical conjunction).

  • Use the guideline ID (for consistency) and the title (for readability) for the links.

  • The Prerequisites field should not contain other text.

Description

  • This field contains a detailed description of the guideline.

  • If needed, add images and tables.

Note

If formal notation (math, regular expression, syntax diagrams, and exact numbers/limits) is available, use it to unambiguously describe a guideline and specify an automated check. However, a human, understandable, informal description must always be provided for daily reference.

Rationale

This field lists the reasons that apply for a given guideline. You can recommend guidelines for one or more of the following reasons:

RationaleDescription
Readability

Easily understood algorithms

  • Readable models

  • Uniform appearance of models, code, and documentation

  • Clean interfaces

  • Professional documentation

Workflow

Effective development process and workflow

  • Ease of maintenance

  • Rapid model changes

  • Reusable components

  • Problem-free exchange of models

  • Model portability

Simulation

Efficient simulation and analysis

  • Simulation speed

  • Simulation memory

  • Model instrumentation

Verification and validation

Ability to verify and validate a model and generated code with:

  • Requirements traceability

  • Testing

  • Problem-free system integration

  • Clean interfaces

Code generation

Generation of code that is efficient and effective for embedded systems

  • Fast software changes

  • Robustness of generated code

Last Change

The Last change field contains the document version number.

Model Advisor Check

The Simulink Check™ product includes Simulink Model Advisor MAAB checks, which correspond to a subset of MAAB guidelines, that you can select and run with the Simulink Model Advisor. In this presentation of the MAAB guidelines, MathWorks includes a Model Advisor check field in guideline descriptions, which contains the title of and a link to the corresponding Model Advisor check, if a check exists. Although this information is included, note that the MAAB working group takes a neutral stance on recommendations for style guide checkers.

For a list of available Model Advisor checks for the MAAB guidelines, see Model Advisor Checks for MAAB Guidelines. For information on using the Model Advisor, see Run Model Checks in the Simulink documentation.