Style is an important aspect of writing, and also of programming. While MATLAB is a quick and easy language in which to program, style should not be neglected. Good style aids readability, which in turn makes it easier to debug and maintain code. It also fosters confidence in the code. Here are six style tips, in which the examples given are all inspired by real-life code that I have come across.
For more on MATLAB style see the book MATLAB Guide, and in particular section 16.1, “Elements of Coding Style”.
1. Omit Unnecessary Parentheses
% Bad style. x = (A')\b; y = ; D = (diag(x));
The parentheses around
A' are unnecessary. Without them, the statement is legal and unambiguous. But of course the parentheses would be necessary in, for example,
x = (A*B)'\c;
y is a scalar. There is no need to enter it as a 1-by-1 matrix by putting it in square brackets.
There is no need for parentheses around the
% Good style. x = A'\b; y = 1; D = diag(x);
2. Use Spaces Consistently
% Bad style. q=sqrt(2); a = 1; Z =zeros(3); for i=1:10, q=q+1/q; end
Stick to a convention about spacing around around equals signs and plus and minus signs. I think spaces make the code more readable.
% Good style. q = sqrt(2); a = 1; Z = zeros(3); for i = 1:10, q = q + 1/q; end
3. Omit Unnecessary Semicolons and Commas
% Bad style. figure; for i = 2:n, x(i) = x(i-1)^2*y(i); end;
Semicolons suppress output, but in this example there is no need for the them since no output is returned by the
end functions. The comma would only be necessary if the
for loop was collapsed onto one line.
% Good style. figure for i = 2:n x(i) = x(i-1)^2*y(i); end
4. Use the Appropriate Construct
if statement is perfectly correct.
% Bad style. if flag == 1 fprintf('Failed to converge.\n') elseif flag == 2 fprintf('Overflow encountered.\n') elseif flag == 3 fprintf('Division by zero.\n') elseif flag == 4 fprintf('Tolerance too small.\n') end
But given its regular structure, it is better written as a
switch statement, which is shorter, brings out the parallelism in the logic, and is easier to check.
% Good style. switch flag case 1, fprintf('Failed to converge.\n') case 2, fprintf('Overflow encountered.\n') case 3, fprintf('Division by zero.\n') case 4, fprintf('Tolerance too small.\n') end
5. Omit Trailing Tildes
In the list of output arguments in a function call a tilde signifies that the output argument in that position is not wanted and so can be discarded (and hence need not be computed). This notation was introduced in MATLAB R2009b. Generally, there is no point in providing a tilde as the last output argument, as a well written function will check the number of requested outputs and not compute any trailing outputs that are not requested.
The singular value decomposition (SVD) of a matrix
A is computed by the call
[U,S,V] = svd(A). In the following example we wish to compute the left singular vectors of A but not the singular values or right singular vectors.
% Bad style. [U,~,~] = svd(A); % Good style [U,~] = svd(A);
An obvious question is why the second example was not shortened to
U = svd(A);
The reason is that with one output argument the
svd function has a special behavior: it returns a matrix of singular values, not the matrix
U of left singular vectors.
6. Include an H1 line in Program Files
The H1 line in a MATLAB program file is a comment line that is the second line in the file and contains the program name followed by a one-line description of the program. It is good practice to provide every program with an H1 line, as MATLAB itself does. Several MATLAB functions make use of H1 lines. For example, when the
help function is invoked with a directory name and the directory in question does not contain a
contents.m file, a list of contents is created from the H1 lines of the program files in the directory and displayed.
Here is an example of a function with an H1-line (this is an updated version of a function from The Matrix Computation Toolbox).
function show(x) %SHOW Display signs of matrix elements. % SHOW(X) displays X in `FORMAT +' form, that is, % with `+', `-' and blank representing positive, negative % and zero elements respectively. f = get(0,'Format'); % Get current numerical format. format + disp(x) format(f) % Restore original numeric format.