MyEnigma

とある自律移動システムエンジニアのブログです。#Robotics #Programing #C++ #Python #MATLAB #Vim #Mathematics #Book #Movie #Traveling #Mac #iPhone

MATLAB Programming Style Guidelines 8: Layout, Comments and Documentation


この記事は,

Datatool社のRichard Johnson氏が書いた

"MATLAB Programming Style Guideline"

を自分なりに翻訳したものです.



この文書は

MATLABのコードをより素晴らしいものにするための

多数のコーディング作法について書かれています.



翻訳結果は以下の各リンクから読むことができます.

0. MATLAB Programming Style Guidelines : About This Document - MY ENIGMA

1. MATLAB Programming Style Guidelines : Introduction - MY ENIGMA

2. MATLAB Programming Style Guidelines : Naming Conventions - MY ENIGMA

3. MATLAB Programming Style Guidelines : Constants and Structures - MY ENIGMA

4. MATLAB Programming Style Guidelines : Functions - MY ENIGMA

5. MATLAB Programming Style Guidelines : General - MY ENIGMA

6. MATLAB Programming Style Guidelines : Files and Organization - MY ENIGMA

7. MATLAB Programming Style Guidelines : Statements - MY ENIGMA

8. MATLAB Programming Style Guidelines : Layout, Comments and Documentation - MY ENIGMA



もし,これらの文章に意見や質問,誤謬などがあれば,

それぞれの記事にコメントしてもらえると幸いです.



また,今回の一連の文章は

リンクフリーです.

また,出典を明確にして頂ければ,

内容の転載も可能です.

その際は,コメント欄を利用して一言お願いします.



この"MATLAB Programming Style Guideline"の英語の原本は

以下のリンクからダウンロードできます.

・MATLAB Programming Style Guidelines - File Exchange - MATLAB Central

・Datatool社のHP

・PDFファイルへの直リンク



また,Richard Johnson氏は,

より詳細なMATLAB Programming Style Guidelineを広めるために,

以下の本を出版しています.

The Elements of MATLAB Style
The Elements of MATLAB Style

もし,より深くMATLABのプログラミング作法を学びたい方は,

こちらも参考にすると良いと思います.



最後に,

今回の翻訳は,Richard Johnson氏に直接許可を頂いています.

Richard Johnson氏の寛大な心と素晴らしい仕事に,

深く感謝します.


レイアウト,コメント,そしてドキュメント

レイアウト

レイアウトに注意を払う理由は,

コードを読んでる読者に,

そのコードを正確に理解してもらうためです.



インデントを気にすることは,

特にコードの構造を再評価するのに役立ちます.

ルール1: 一つの行のコードは80文字で済ますべきです.

80文字とは,

エディタや,ターミナルエミュレータ,プリンタ,

デバッガやファイルなどの複数の人が利用するものでは,

一般的な大きさです.



このルールを守ったファイルであれば,

もしプログラマ間で,ファイルを受け渡ししても,

意図しない所で文章が切れることなく,

可読性が向上します.


ルール2: コードは程良い場所で切るべきです.

もし,一つのコードが80文字を超えたら,

行を分けましょう.

一般的には,

・カンマやスペースの後に区切る

・演算子の後に区切る

・新しい行は,その前の行の

 区切られた数式が始まる場所に合せて並べる.

というルールを守りましょう.

ex)

totalSum = a + b + c + ...
                d + e;
function (param1, param2,...
               param3)
setText ([‘Long line split’ ...
              ‘into two parts.’]);

ルール2: 基本的にインデントは3は4スペースにする.

インデントが統一するということは,

プログラムの構造を再構築する上で

非常に有効な方法です.

インデントが1というのは,

コードの論理的なレイアウトを協調するには,

いささか小さすぎます.

インデントが2というのは,

しばしば,ネストしたコードにおいて

一行を80文字以内にするというルールを守るために,

提案される方法ですが,

MATLABでは基本的に

そこまで深いネストというのはしないことになっています.

インデントが4以上というのは,

ネストしたコードが途中で切られてしまうので,

コードが非常に読みにくくなってしまいます.

現在のMATLABエディタのデフォルトインデントは4になっています.

インデントが3というのは,

以前のエディタのデフォルトだったようです.


ルール3: インデントはMATLABエディタの機能を使って統一すべきです.

MATLABエディタには,自動的にコードの構造を解析して,

C++やJavaのルールに基づいてインデントを揃える機能があります.

インデントを統一する時には,

これを使用しましょう.


ルール4: 一行のコード内には,1つだけの実行コードを書くべきです.

このルールはコードの可読性を向上させ,

コードのJIT*1を推し進めることができます.


ルール5: ifやfor, whileを使用した短いコードの場合,一行に書いても良い.

このルールを使用すれば,コードがよりコンパクトになりますが,

デメリットとして,構文の目印となるインデントが無くなってしまいます.


ex)

if(condition), statement; end
while(condition), statement; end
for iTest = 1:nTest, statement; end

余白

コードにおける余白は,それぞれのコードのコンポーネントを

目立たせることにより,コードの可読性を向上させます.


ルール1: = や &, | の前後にはスペースを入れる.

このような特殊な文字の前後にスペースを入れることは,

そのコードの左右の項を見かけで分割する

非常によい手がかりになります.

このように二値の論理演算子の前後にスペースを入れることは,

複雑な式のそれぞれの項を分類する良い方法になります.

ex)

simpleSum = firstTerm+secondTerm;

ルール2: カンマの後にはスペースを入れても良い

これらのスペースはコードの可読性を向上させます.

しかし,プログラマの中には,

コードが長くなって分断されるのを防ぐために,

このルールを利用しない人もいるようです.

foo(alpha, beta, gamma)
foo(alpha,beta,gamma)

ルール3: 一行に複数のコマンド入れた場合のセミコロンやカンマに関しては,その後にスペースを入れるべきです.

このスペースはコードの可読性を向上させます.

if (pi>1), disp(‘Yes’), end

ルール4: 複数のグループにまとめられるコードは,一行の空行によって分割しましょう.

このように空欄をそれぞれのコードユニットに挿入することにより,

コードの可読性が向上します.


ルール5: グループよりも大きいブロックに分けられるコードは,複数行による空行で分割しましょう.

このルールを実現する一つの方法は,

それぞれのコードブロックを三行の空行で分ける方法である.

普通の空行より大きい空行で分割することにより,

ファイルの中でそのブロックを目立たせることができます.



もう一つの実現方法として,

コメントで*や-といった文字を繰り返して,

区切り線を作るという方法もあります.

ex)

*************************************

*---------------------------------------------

ルール6: コードの可読性を向上させたい所では位置合わせをする.

コードの位置合わせは,

それぞれの式を分割して,

より読みやすく,理解しやすくすることができます.

このように位置合わせされた美しいレイアウトは

コードの見えないエラーを見つけ出す助けになります.

weightedPopulation = (doctorWeight * nDoctors) + ...
                     (lawyerWeight * nLawyers) + ...
                     (chiefWeight *  nChiefs);

コメント

コメントを付記する目的は,

コードに情報を付加することです.

一般的にはコメントはそのコードの使用方法を説明します.

また,参考情報やそのコードの振る舞いの理由説明,

その関数の限界,そして今後必要な改善内容なども記述されます.

これまでの経験で,

コメントは後でコードに付記するのではなく,

コードを書きながら同時にコメントを書く方が

良いと思います.


ルール1: コメントは出来の悪いコードを改善したりはしない.

コメントによって,適切な名前を選択しなかったコードや,

明確な論理構造を持たなかった

コードの埋め合わせをすることはできません.

そのようなコードはコメントを書く前に,

書き直すべきです.

Steve McConnellも言っています.

“コード自体を改善しましょう.

 そしてその後,そのコードをより綺麗にするために,

 コメントを書きましょう.”


ルール2: コメントはコードの内容に忠実であるべきです.しかし,コード自体が述べること以上のことをコメントは述べるべきです.

ダメなコメントや使えないコメントは,

コードの読者の邪魔をするだけです.

N. Schryerは言っています.

"もしコードとコメントが一致していない時,

それはコードもコメントも両方が間違っている可能性が高いです"

一般的に,コメントというのは,

"なぜ"や"どうやって"に答えることよりも,

それが"なに"なのかを答えることの方が重要なのです.



**ルール3: コメントは読みやすくあるべきです.

コメントの文章と%の間にはスペースを入れるべきです.

また,コメントの初めは大文字で始まるべきであり,

最後はピリオドで終わるべきです.


ルール4: コメントもコードと同じインデントルールに従うべきです.


このルールはプログラムのレイアウトを

コメントが破壊しないようにするためです.


ルール5: 関数のヘッダーコメントは,"help"や"lookfor"コマンドが検索できるようにするべきです.

"help"コマンドは関数のファイルの最初のコメントブロックを表示する関数です.

これは関数の内容を確認するのに,非常に役立ちます.

"look for"コマンドはパス上のすべてのm-fileの

最初のコメントラインを検索します.

この行には,検索しやすい単語を含めるべきでしょう.


ルール6: 関数ヘッダーコメントでは,入力値の条件などを明確に述べるべきです.

基本的に関数のユーザは,

その関数の入力値が,

特別な単位や行列の型をしているのかどうかが

気になるものです.

ex)

% ejectionFraction must be between 0 and 1, not a percentage.
% elapsedTimeSeconds must be one dimensional.

ルール7: 関数ヘッダーコメントにはその関数の副作用についても記述しましょう.


関数の副作用とは,その関数の出力値以外の

プログラムに影響する事柄すべてを指します.

例えば副作用の一つの例は,

グラフのプロット機能などです.

よって,副作用の記述は関数のヘッダーコメントに入れて,

"help"コマンドによって,表示できるようにするべきでしょう.



**ルール8: 関数ヘッダーをhelpコマンドで表示させた時に,内容が読みにくくなるのは避けましょう.


関数ファイルの一番最初にコピーライトを書いたり,

変更履歴を書くことは一般的です.

しかし,この場合,関数ヘッダーコメントと,

これらの情報の間には,

一行空行を入れるべきでしょう.

これによって,

helpコマンドによって,

それらの情報が表示されることを防ぐことができます.


ルール8: コメントは英語で書かれるべきです.

グローバルに使用される関数を目指す場合,

英語が適切な言語でしょう.


ドキュメント

ルール1: 一般的なドキュメント

役に立つドキュメントを書くためには,

そのコードが何をしようとしているのか(要求)に関する

読みやすい文章を書くべきです.

同様に,それのコードがどうやって動くのか(設計)

どの関数が他の関数に依存していて,

どうやってその関数が他のコードに使用されているのか

(インターフェイス)

そして,そのコードはどのようにテストされたのか,

を正確に記述すべきです.

また,追加の文章として,

メンテナンスや拡張するための

他の解決方法や提案に関する議論を記述すべきです.

Dick Brandonは言いました.

"コードのドキュメントとセックスは似ている.

いい時は,とてもとてもいい.

しかし,駄目な時は無いよりはマシぐらいになる."


ルール2: まず初めにドキュメントを書くことを考えましょう.

プログラマの中には,

"コードが先だ.質問には後で答える"

という方法が一番だと思っている人が多いようです.

しかし,

多くの人が経験していることですが,

きちんと設計して,それを実装したほうが,

よりすばらしい結果を生みやすいようです.

開発のプロジェクトというのは,

大抵,スケジュール通りに行かないものです.

もし,ドキュメントを書くことや

テストを行うことを放置していると,

結局それは最後まで実行されませんし,

もしかしたら,永久に実施されないかもしれません.

ドキュメントを一番最初に書くことは,

当然ドキュメントを必ず作成することに繋がりますし,

おそらく開発工数を減らすことになるでしょう.


ルール3: コード変更

コードやドキュメントの変更をコントロールする際に

プロがよく使用する方法は,

ソース管理ツールを使うことです.

一方,とてもシンプルなプロジェクトの場合,

以下の例のように,

変更履歴をコメントとして,

関数ファイルに記載しておくべきでしょう.

% 24 November 1971, D.B. Cooper, exit conditions modified.

MyEnigma Supporters

もしこの記事が参考になり、

ブログをサポートしたいと思われた方は、

こちらからよろしくお願いします。

myenigma.hatenablog.com

*1:おそらくJust In Timeのこと.必要なコードを必要な時に使うという意味だと思う