Improve Toolbox before publishing / best practices

Question

Frederik 2018-2-6

1
链接

此问题的直接链接

https://ww2.mathworks.cn/matlabcentral/answers/381068-improve-toolbox-before-publishing-best-practices

评论： Adam Danz 2019-10-27

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

0 个评论
显示 -2更早的评论隐藏 -2更早的评论

请先登录，再进行评论。

请先登录，再回答此问题。

Answer 1

Image Analyst 2018-2-6

1
链接

此回答的直接链接

https://ww2.mathworks.cn/matlabcentral/answers/381068-improve-toolbox-before-publishing-best-practices#answer_303709

comment_counter.m

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

1 个评论
显示 -1更早的评论隐藏 -1更早的评论

Adam Danz 2019-10-27

+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 2018-2-6

1
链接

此回答的直接链接

https://ww2.mathworks.cn/matlabcentral/answers/381068-improve-toolbox-before-publishing-best-practices#answer_303719

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.