Matlab 教材：函式之註解與線上說明

這裡介紹一個新的算子：註解符號 % 它的意思是讓 Matlab 無視於這個符號和它以後的整列文字。 註解符號之後的文字，稱為註解文字，或者就說是註解。 既然 Matlab 無視於註解的存在，當然就不會執行它們。 既然 Matlab 不看它們，它們寫在那裡當然是寫給人看的。 通常是註解寫在原始碼裡面，解釋原始碼的意義、 或者提醒原始碼有什麼錯誤或什麼未盡之處、 或者紀錄寫這段原始碼的歷史、心得或心情等等。

繼續使用 collatz.m 為例，我們可以在『驗明輸入』那一段原始碼之前， 加一列

% Input validation: is a scalar, is an integer, is positive.
那麼將來讀到這個原始碼的人 (也可能是未來的您自己)， 就會知道以下這些奇怪的程式是在幹甚麼。

然後，在『驗明輸入』之後，也可以加一句註解，說

% Let x be x_0, start the Collatz sequence x_n, n=1,2,3...
% until the first x_n = 1
上述三列都是給人看的，完全不影響 Matlab 的操作。

註解也可以是中文，並不影響 Matlab 的操作。 但是為了預防將來要閱讀原始碼的人可能沒有中文作業系統、中文視窗或是中文字型， 以至於無法閱讀中文註解，所以註解最好還是用 ASCII 字碼， 這是最保險的字碼。

當我們說

>> help sum
會看到 sum() 的線上說明。 雖然「線上說明」不見得有用，但是有總比沒有好。 其實 Matlab 函式的線上說明是以一個非常簡單的方式處理的： 函式原始碼中第一批連續的註解，就是線上說明。看以下的例子。 
function n = collatz(x)
% Usage: collatz(x)
% Here x is a positive integer, let it be x_0 and generate the
% Collatz sequence until the first n such that x_n = 1.  Return n.
%
% Shann 2004-04-29

% Input validation: is a scalar, is an integer, is positive.
if (length(x) > 1)
    disp(['Error: input must be a scalar.']);
    return;
end
if (floor(x) ~= x)
    disp(['Error: input must be an integer.']);
    return;
end
if (x < 1)
    disp(['Error: input must be a positive integer.']);
    return;
end

% Let x be x_0, start the Collatz sequence x_n, n=1,2,3...
% until the first x_n = 1
n=0;
while (x>1) & (n<1000)
    n = n+1;
    if (rem(x,2))
        x = 3*x+1;
    else
        x = x/2;
    end
end

那麼，如果有人輸入

>> help collatz
就會看到以下線上說明文字： 
Usage: collatz(x)
Here x is a positive integer, let it be x_0 and generate the
Collatz sequence until the first n such that x_n = 1.  Return n.

Shann 2004-04-29
注意 Shann 前面有一個空列，那是由一列空的註解造成的。

線上說明可以用中文寫，但是如果 Matlab 並未在一個中文視窗中執行， 就可能看不到中文的線上說明。

習題

  1. 修改 collatz() 函式，使得萬一 n 到達 1000 而 x 尚未出現 1 的話，正常結束程式並送回答案 (n=1000)， 但是顯示一句警告訊息 Warning: number of iteration exceeded. 這或許是一句令人興奮的警告。您怎樣測試這個程式改得正確？
單維彰 (2004/04/29) --- [Prev] [Next] [Up]