James West

When I first saw this, I wondered why it is necessary. After all, this alternative works very nicely.

V = V./norm(V);

I'll admit that there is no test for a zero norm, but neither does this code have a check for divide by zero. And my line is far shorter than what you need to type to use this code.

V = fcn_createUnitVector(V);

Worse, what kind of name is that? How will I ever remember that name? It is far easier to just use the trivial replacement line that I showed. In fact, a nice thing about my alternative is it works properly for any length vector, and you can choose how to define the norm of V. So if you prefer to use a 1-norm, that is also trivial.

How about the help? Here it is:

%Author: Jim West
%Date: 7/12/2010
%Use: [vectorOut] = fcn_createUnitVector(vectorIn[1x3])
%Description: This function will simplify the process of creating a unit
%vector in one direction by dividing a vector by its length.
%The points should be [x1 y1 z1];

See that the very first line of the help is NOT an H1 line. An H1 line is what the lookfor function uses, as well as other tools in matlab. lookfor helps you, because the next time you want to find this little toy, you will never remember the name "fcn_createUnitVector" a month from now, or next year. An H1 line should be the VERY FIRST LINE OF COMMENT. It should contain a descriptive line, with intelligently chosen keywords that lookfor will search through. The line

%Author: Jim West

simply fails to cut the mustard as an H1 line.

The code does have ONE error check, but even that is problematic. Take a look.

[r c] = size(vector);
%Check for appropriate sizes
if (not(r == 3) && not(c==1)) && (not(r==1) && not(c==3))
error('Input not appropriate for creating unit vectors. Must be 3x3 rotation matrix');
end

See that if the input is not a 1x3 or 3x1 vector, it fails, but then tells you that it requires a 3x3 rotation matrix!!!!! Of course, this is completely inconsistent with the help, or the purpose of the code.

Other problems with the help are that it always returns a row vector, but no mention of that fact is made. This would be a surprise to the user who passes in a column vector, expecting to see a new column vector as output. (Yes, the help implies that the input should be specifically a row vector, but the code actually allows a column vector as input!)

Finally, I'll point out that the help states that it divides by the length of the vector. Good help would make it clear that the length used is a 2-norm, the sqrt of the sum of squares.

I'm feeling very generous this day, so I'll give it 2 stars.