MATLAB Community

MATLAB, community & more

Getting By With a Little Help 2

Posted by Ned Gulley,

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.

addme

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

cardioid

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

Note

Comments are closed.

2 CommentsOldest to Newest

Chad Greene replied on : 1 of 2
I like this post because I'm a big champion of clear documentation, but there seems to be a logical disconnect between Matlab syntax and the syntax shown above. Namely, in the header shown above, ADDME is written in all caps even though the function name is lowercase. Matlab is case sensitive, so each time I write function documentation I'm faced with the decision: In the header should I give unambiguous examples of how to use my function with the correct case, or do I give slightly incorrect examples that follow the syntax above? Does case matter in function headers?
Ned Gulley replied on : 2 of 2
Hi Chad. You've put your finger on a touchy legacy issue. Historically we've used all caps to distinguish function names from other text. This is because we're often displaying help text in terminals that don't have the means to distinguish text with font styling or coloring. There is an obvious downside, as you point out: the function name shown is literally incorrect. MATLAB's interpreter doesn't recognize the all-caps version of the function name. This is especially problematic with mixed-case names, since you can't assume that you just need to lower all the characters to get the function name. TL;DR: It's okay to use the exact and appropriate spelling of your code if you like.