MATLAB Toolbox Best Practices

Version Number CC-BY-4.0 License

You have a MATLAB® toolbox that you want to share with the world. We want to help. Apply these MathWorks Toolbox best practices. It's a little bit of extra work with a big payoff.

This is a continuously evolving document and some best practices may change in the future as MATLAB evolves. We encourage your feedback and suggestions for future revisions. Feel free to open an issue or post to the discussions. Your insights and feedback help us improve this document and make it even more useful for the community. We've added information on how to integrate MEX functions, and plan to add recommendations around content-obscured files (P-Code).

Being in a standard format makes it easier for other people to assess and take advantage of your work. Your work is more "legible," because it's in a familiar format. They know, for example, that they can always expect to find a helpful and thorough README.md file in the top folder. They also know that a good place to start learning how to use your toolbox will be the doc/GettingStarted.mlx file. These and other best practices help your users build confidence that your toolbox is well built and ready to use.

But the advantages go beyond helping your users. Standard formats also make it easier for you to maintain the toolbox. Tools and systems (such as automated testing on GitHub) will immediately know how to work.

We use the term “toolbox” here to mean a collection of reusable MATLAB code that you want to share with other people. Toolboxes contain not just code files, but also data, apps, tests, and examples. Some toolboxes will be just a few files; others may be extensive and represent years of effort by multiple people. The guidelines we present can be adapted for toolboxes that are large or small, casual or sophisticated. We will step through a comprehensive example with many aspects. There’s no need to do everything all at once -- you can start with a few guidelines and adopt more as you go.

To make it easier to follow, we’ve created a fictitious toolbox for doing basic arithmetic: The Arithmetic Toolbox on GitHub. We’ll use this throughout to show how to apply these design principles. If you'd like to explore a complete toolbox that uses this structure, visit the Climate Data Store Toolbox.

TL;DR

Root folder is a shortened version of the name of the toolbox
Put all the materials that you plan to share with your users in toolboxsub-folder
Provide a GettingStarted.mlx in toolbox/doc folder to help people get started
Package and distribute your toolbox with MATLAB Toolbox files (.mltbx)
Make your toolbox more robust by using tests, MATLAB Projects, source control, and buildtool
Add the "Open in MATLAB Online" badge so users can try out your toolbox instantly
See MEX.md in this repository for recommendations on using MEX functions in your toolbox

Recommended file and folder structure:

<toolboxname>/
|   README.md                    # Overview of toolbox for users and developers
|   license.txt                  # License file
└───images/                      # Images for README.md
└───toolbox/
    |   <toolboxfunction1>.m     # Documented functions
    |   <toolboxfunction2>.m
    ├───doc/                     
    |       GettingStarted.mlx   # Getting started guide
    ├───examples/                # Examples (Live Scripts)
    └───private/                 # Implementation details, not intended for end users

Root Folder Name and Contents

At the top level of your project is a folder or source repository, which we'll call the root folder. This folder has everything a developer needs to collaborate with you on your toolbox. When you are working in GitHub, this is the repository name, and will be the name of the folder when the repository is cloned.

To name the root folder of your toolbox, shorten the English name by removing the word "toolbox" and start with a letter. Use only letters, numbers, and underscores. For instance, if your toolbox is named "QuickerSim CFD Toolbox for MATLAB," the root folder might be named "quickerSimCFD." Following this naming convention will guarantee the validity of your toolbox in every operating system and source control system you use, eliminating the need to rename it in the future whenever you migrate to new systems.
Include a README.md file in the root folder. See this article for a good tutorial. Start with a short, user focused summary of the toolbox with installation instructions, and then point them to your GettingStarted.mlx file (see below). The rest of your README.md should be written for collaborators working on the toolbox, and how to contribute to it. It is a historical convention (more than 50 years!) that the file name be capitalized to make it stand out.
A license.txt file outlines how others can use, distribute, and change your code. Including a license file adds clarity and transparency for other people. Without a license, others may not be sure if they're allowed to use or change your code.
You should put images for your README.md file in an images folder to reduce clutter.
See below for information on where to put tests, MATLAB projects, and automation files.

Our example toolbox starts with a README.md with a single image, plus a license.txt file.

arithmetic/
|   README.md
|   license.txt
└───images/
        readmeImage.jpg

Toolbox Folder

The toolbox folder is where you store all the materials that you plan to share with your users, including code, apps, and examples. Storing these materials in a single folder makes it clear what is going to be distributed to users, and what is not. The folder is named toolbox and placed under the root folder.

The structure of your toolbox folder should reflect its size and complexity:

For projects with fewer than 20 functions or classes, put the documented functions that you expect users to call directly at the top level of the toolbox folder. Any helper functions or implementation details that users shouldn't access should go in a private subfolder. Functions and classes in this special folder are only accessible to code in its parent folder, keeping internal logic hidden.
For larger projects, put the most commonly used functions and classes at the top level of the toolbox folder. Then, group additional specialized functions into folders by functionality. To keep things even more organized, consider using namespaces (see below) to organize your functions and classes into logical groups. Internal implementation code should be placed in a <toolboxname>.internal namespace. Functions in this namespace are callable with the full name, e.g. arithmetic.internal.intToWord. While this code is callable by end users of your toolbox, the full name makes it clear that the code is not intended for end users.

We also recommend including in your toolbox folder:

A GettingStarted.mlx file that introduces your users to your toolbox and showcase important workflows. This file should give an overview of how to use your toolbox and highlight key functionality. Put this file in a doc folder under the toolbox folder. This specific name and location will come in handy later since it ensures your end users will be shown the GettingStarted.mlx file when they install your toolbox.
Examples are an effective way for users to learn how to use your toolbox. We recommend using MATLAB Live Scripts to show how to use different parts of your toolbox and including them in an examples folder under the toolbox folder. This makes it easier for users to explore and try out different code samples.

Our example toolbox has:

A doc folder with a GettingStarted.mlx script.
A function for users called add.m.
An examples folder with MATLAB Live Scripts showing different ways the toolbox can be used.
A private function, intToWord.m that isn't intended for end users.

arithmetic/
:
└───toolbox/
    |   add.m
    ├───doc/
    |       GettingStarted.mlx
    ├───examples/
    |       usingAdd.mlx
    └───private/
            intToWord.m

Enhancing your toolbox

MATLAB offers various features to make your toolbox more intuitive and user-friendly. We recommend the following to improve the quality of your toolbox:

Suggestions and Argument Validation: To enhance your user's experience when using your functions, you can add an arguments block to create customized tab completion suggestions. This was introduced in R2019a. Additionally, MATLAB will verify the type, size, and values passed to your function, enabling users to call your function correctly. See the Function Argument Validation documentation for more information. If you need more control over tab completion, create

Toolboxdesign

Install / Use

README