Let’s say you’ve written some code that you think might worth adding to the File Exchange. But then you hesitate. Your Tiddlywinks Trajectory Simulator function (TiddleSim.m) is nifty. It’ll definitely be the first of its kind on the site. But you ask yourself: Should I really put this on the File Exchange? Or will everybody think I’m lame and criticize me for being a bad coder?

My friend, I’m here to encourage you to submit that file.

Not everybody will find it interesting, but I guarantee you someone will. And I know the secret to dramatically increasing the number of people who find it interesting. Here it is.

The very best way to get people to use and enjoy your code is to include some help and examples in your function comments.

Is there a standard way to do that? Yes there is. Take a look at this documentation page. It spells out how we structure function help here at MathWorks. You don’t have to use this format, but it’s served us very well, and if you do you’ll be using a standard that people around the world are familiar with. So I’m going to strongly recommend that you use it unless you have compelling reasons not to.

The anatomy of function help, at its simplest, is this. Just below the function signature you put the H1 line. This is followed by the calling syntax. At the end you might want to link to other functions in a See Also line.

Here is a sophisticated function called ADDME. We’ll use it as our help model.

The H1 line is very cleverly named. It is the first line you see when you type help on the function (that is, “help addme”). The H1 lines starts with the name of the function followed by a short sentence (it has to fit on one line!) describing the function.

If you’ve made it this far and you really want to rock the world with your function, add some examples to your help. That way people can see not only the abstract calling syntax, but also how it looks in action.

I dipped into the File Exchange and found a popular function with terrific help: Fast ‘n easy smoothing written by Damien Garcia. Download it and look at the help. It starts off like this.

>> help smoothn
smoothn Robust spline smoothing for 1-D to N-D data.
   smoothn provides a fast, automatized and robust discretized spline
   smoothing for data of arbitrary dimension.

But it goes on and on from there, with lots of detail and references, and no fewer than eight (!) examples. Beautiful! That, my friends, is how you make your code helpful.

Since Damien works in a lab that does heart imaging, it’s only appropriate that I should include this example from his file: smoothing a cardioid.

 t = linspace(0,2*pi,1000);
 x = 2*cos(t).*(1-cos(t)) + randn(size(t))*0.1;
 y = 2*sin(t).*(1-cos(t)) + randn(size(t))*0.1;
 z = smoothn({x,y});
 plot(x,y,'r.',z{1},z{2},'k','linewidth',2)
 axis equal tight

Be like Damien. Have a heart. Think of your File Exchange friends. A little help can make all the difference.