Improve Toolbox before publishing / best practices

I have a collection of functions and Simulink-Models which might be worth publishing to help other researchers in my field. However the quality of these files varies and I would like to get them ready for other people. Is there a collection of 'best practices' or some kind of a checklist what to look for before publication?

What I already did:

• Rewrote the more shady functions while using the MATLAB Programming Style Guidelines and observing Top 10 MATLAB code practices that make me cry
• Included a demo-script which implememts a basic demonstration
• Added Masks to the Simulink function blocks to label Inputs/Outputs and the Parameters passed to the function
• Added help text for every mask

I would like to get more thoughts and hints on this topic.

Frederik

Answer 1

[Image Analyst]

Put double the number of comments into the source code as you think you need.

No one ever complains about too many explanatory statements embedded in the source code. The more the better. Sometimes (later) even when I look over my own code, I'd have trouble understanding what it did if I hadn't put in a comment to explain it.

I'm attaching a comment counter program that I wrote. For comparison, 35% of my code lines are a

[Adam Danz]

+1

This function should be on the file exchange!

"No one ever complains about too many explanatory statements"

I've been flooding my files with comments including detailed descriptions at the top, inline comments throughout the code, and a list of footnotes at the end. The result is that a simple 10-line function turns into 50 lines and sometimes I ask myself it it's too much but I imagine some day I or someone else will benefit from knowing the background to decisions that were made while writing the code.

Answer 2

[Steven Lord]

Consider writing some basic tests for your functions.

Don't be worried that this page appears in the "Advanced Software Development" section of the documentation. Script-based tests are easy to write as long as you know how to write code sections (starting with %%) and use the assert function.

Function-based and class-based tests provide additional functionality (more advanced setup and teardown capabilities, for example) at the cost of more complexity. But even basic script-based tests can prove invaluable when your users start modifying your functions. Their failures will (or should) alert those users when their changes impact the expected behavior of the functions in ways they didn't expect.

[Adam Danz]

+1 another great idea that should be more commonly used!