MathWorks releases Best Practices for MATLAB Toolbox development

Posted by Mike Croucher, June 15, 2023

20 views (last 30 days) | 0 Likes | 3 comments

Research computing can be a messy affair and, for me at least, it often looks like the following. First, there is the exploration phase where you often have no strong idea about what you are doing. You play around with the data or simulation, see what there is to see, learning about both your subject domain and, often, the system you are developing on (e.g. MATLAB, Python, R etc) simultaneously.  

As our understating improves, and the complexity of the narrative increases, the messy script or notebook becomes a tidier one. Structure emerges in the form of reusable functions and classes, initially just for ourselves, but eventually for other people.  Documentation that starts out as a few scattered comments becomes more coherent and comprehensive.  Your test script evolves into unit tests which become part of a continuous integration process. 

Your private repository becomes a public one and other people start expressing an interest in your work.  You turn your code into a package to allow others to more easily install it and a ‘Getting started’ guide to help onboard them.   

On and on it goes and the realization hits you: Now you are a software engineer as well as a researcher.  A Research Software Engineer maybe? Your journey to this point may be different from the one I outlined above but the end point is usually the same: 

You’ve written (or are writing) a MATLAB Toolbox and want to know what the best practices are so you can make it as good as can be.   

Feedback from toolbox authors

Yesterday, we got together with a bunch of prominent open-source MATLAB toolbox authors and asked them “What problems do users have with your toolbox?”.  The results were illuminating  

Ideally, everyone could develop and release toolboxes in a way that minimised these problems. Wouldn’t it be great if MathWorks offered advice on how to go about doing that? 

Well, we’ve got you covered with some new repositories on the MathWorks GitHub organisation 

MATLAB Toolbox Best Practices: Our current set of suggestions for how a good MATLAB Toolbox should be developed and released.
Example MATLAB Toolbox: A fictitious toolbox created solely to demonstrate the best practices.

You’ll learn things like how to structure your toolbox, where to put examples and documentation, how to keep development code separate from shipping code and, perhaps most importantly, how to get all those cool badges on your repo that you see the professionals use. Such as this one 

Developed by the community team at MathWorks, these are evolving documents that don’t yet cover everything.  We invite you to open an issue or post to the discussions if you have any questions, comments or suggestions about what has been done so far. Also feel free to comment here or message me on Linkedin or twitter.  