モチベーション
matlabを使って10年ぐらいたつが，関数コメントをどう書くべきか，未だに悩むので改めて整理する。
関数コメントの書き方
基本は，mathworksのプログラムへのヘルプの追加に従う。
- 1行目に関数名（なぜか大文字）と概要を書く
- 2行目以降に使い方を書く。引数省略ができる場合は省略した形も書く。
- 中段に引数と戻り値の情報を書く（これは私ルール。詳細後述）
- 最終行に関連するプログラムの情報を書く（doc, help でコメント出力すると，リンクが張られる）
関数コメントの例
簡単な線形探索プログラムに対して，コメントを与えた。
linear_search.m
function is_match = linear_search(key, input_nums)
%LINEAR_SEARCH 線形探索
%
% is_match = linear_search(key, input_nums)
%
% Parameters
% ----------
% key : numeric
% 検索する数
% input_nums : vector(numeric)
% 検索対象である数値配列
%
% Returns
% -------
% is_match : vector(bool)
% 一致していればtrue,それ以外ならfalseを格納
%
% see also: find
% 引数チェック
validateattributes(key,{'numeric'},{'scalar'})
validateattributes(input_nums,{'numeric'},{'vector'})
% 格納先準備
N = length(input_nums);
is_match = false(N, 1);
% 線形探索
for index = 1:length(input_nums)
if(key == input_nums(index))
is_match(index) = true;
end
end
end
コマンドウィンドウでdoc linear_search とすると，以下のような画面が出る。
help linear_searchとすると，コマンドウィンドウ上にヘルプが出力される（出力結果は省略）。
matlab関数の引数と戻り値について
matlabは型を定義しないなので，できれば関数コメント内に引数と戻り値の情報を書いておくべきだと思います。とくに,matlabはアカデミックなユーザーが多いので，平気でNやalphaといったシンプルすぎる変数名が出てきます。
では関数コメント内でどう書くべきかというと，特にこれといったスタイルはMatlab業界にないようです（あれば教えてください）。そこで，上記サンプルではpythonのnumpyスタイルを参考に記述しました。numpyスタイル以外にも，googleスタイルなどがあるので，これらを参考に書き方を決めていきましょう。
また，型をどう書けばいいか，という問題もありますが，私はvalidateattributesと合わせた書き方がよいと思います。上記サンプルでは，関数の冒頭で，引数のkeyが，numericかつscalarであることをチェックしています。validateattributesはとても柔軟で，正数や整数といった，アルゴリズム操作で頻繁に登場する条件もチェックできるので，積極的に使っていきましょう。