MyEnigma

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

MATLAB Programming Style Guidelines 2: Naming Conventions

この記事は,

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氏の寛大な心と素晴らしい仕事に,

深く感謝します.



Naming Conventions

コーディングにおける

変数や関数のネーミングルールを作成することは,

非常に議論の的になりがちです.

この章では非常に一般的なネーミングルールだけを述べることにします.

一人ひとりのプログラマがこれらのルールを守ることがとても重要なのです.


変数のネーミングルール

ルール1: 変数の名前は,その変数の意味や使い方を示すべきです.

単純な記号や英単語の頭文字を

変数名にするのではなく,

誰もが理解できるように,

意味を持つ単語・文章を変数名にしましょう.


例) 三角形の高さを示す変数

◯: height=1;

×: h=1;


ルール2: 変数の名前は,小文字で始めるべきです.

変数の名前は小文字で初めて,

複数の単語をつなげる時は,

それらの単語のの頭文字だけを大文字にしましょう.

(ex: linearity, credibleThreat, qualityOfLife)



このルールは基本的にC++の開発コミュニティで使用されているものです.

しかし,MATLABを開発しているMath Worksでは

大文字で始まる変数を使用することがあるようです.

しかし,これは他の言語で予約されている変数の型や構造体の名前を使う時だけのようです.



もう一つの変数のネーミング方法として,

アンダースコアで複数の変数名をつなげる方法があります.

この方法は非常に変数名を読みやすくしますが,

他の言語の変数名のネーミング規則を見ると,

一般的ではないようです.



また,Texのインタープリタを使っている

MATLABのFigureの凡例やタイトルでは,

アンダースコアを使うと,

勝手に後ろの文字を下付きに変換にしてしまうので,

やはりMATLABでは

アンダースコアは使わないほうがいいでしょう.


ルール3: スコープの大きい変数には変数の意味を表す名前を.小さい変数は短い名前を.

スコープが大きい変数,

つまり,使用される時間や回数が多い変数は,

その変数の意味を表す名前にすべきです.

一方,スコープが小さい変数,

つまり,すぐに使われなくなってしまう変数は,

短い名前にすべきなのです.



実際には,殆どの変数の名前は意味を持つ名前にすべきです.

短い名前を使うときは,

そのプログラムの構造を明確にすべき時だけ使うべきです.

例えば,一時的な格納用変数や各種の添字は,

短い名前にすべきなのです.


つまり,

これらの短い名前の変数を見たプログラマが

この変数は,その変数が書かれている

前後数行のコード内だけで使用されるだろうと

仮定できるようにしなければなりません.


また,

これらの短い名前の変数は,

int型の場合,i,j,k,m,nなどを使用し,

double型の時には,x,y,zなどを使用すべきです.



ルール4: 変数の前に"n"を付けた場合,その変数はオブジェクトの数を示します.

あるオブジェクトの個数を格納する変数は,このルールに従いましょう.

このルールは数学で使用されています.

ex:

・ファイルの数を示す変数 -> nFiles

・セグメントの数を示す変数 -> nSegments


ルール5: 複数形の表記については一貫性を持つ

変数名において,単数形で表記するか複数形で表記するか,

という問題に関しては,

必ずどちらかに統一すべきです.



最後に複数形の"s"が付くかどうかだけで,

2つの変数が存在することは,

防ぐべきです.

ex) pointとpointsという2つの変数が共存するコードなど.



この問題を解決する方法の一つとして,

複数形を取りたい変数には,

変数名の後ろに"Array"を付けるという方法があります.

ex) 単数形: point, 複数形: pointArray


ルール6: インデックスを表す変数は,後ろに"No"を付けるか,前に"i"をつける.

あるオブジェクトのインデックスやナンバーを示す変数には,

後ろに"No"を付けましょう.

これも数学の分野で使用されている方法です.

ex) tableNo, employeeNo



前に"i"を付けるのもいいでしょう.

ただ,どちらかに統一すべきです.

ex) iTable, iEmployee


ルール7: イテレータには,i,j,kを名前にするか,前につける.

forループなどで使用されるイテレータには,

i,j,kという名前を付けるか,

i,j,kを変数名の前につけましょう.

これも数学でよく使用されるルールです.

ex)

for iFile = 1:nFiles
        hogehoge;
end

注意しなくてはいけないのは,

複雑なアプリケーションだと,

イテレータ以外にiやjといった変数名が使用されていることがあります.

(ex: 虚数にjを使うなど)

なので,イテレータでは,i,j,kを変数名の前に付けて,

よりユニークな名前にすべきです.



また,ループをネストした場合,イテレータの変数名につけるi,j,kは

アルファベット順につけるべきです.

同様に,ループをネストした場合,

イテレータの混同を防ぐため,

イテレータの変数名は

より一層,ユニークな名前にすべきです.

ex)

for iFile = 1:nFiles
   for jPosition = 1:nPositions
       hogehoge;
   : end
: end

ルール8: 否定語を使ったブール変数は使用しない

もし,ブール変数を使用する場合には,

否定を基本とした変数は使わないようにしましょう.

なぜなら,論理演算する際に,

二重否定をする必要性が出る場合もありますし,

統一しなけば,勘違いする可能性があるからです.

ex) ◯: isFound ×:isNotFound



ルール9: 大文字で使用されているアクロニムでも,すべて小文字を使うか,先頭だけを大文字にする.

大文字で使用されているアクロニムをそのまま変数名を使用すると,

以前に述べたルールに合わなくなってしまいます.

しかし,例えばdVD,やhTMLなどのように,

大文字のアクロニウムの先頭を小文字にすると,非常に読みにくくなります.

特に,複数の単語の頭文字を繋げた変数名の場合,

例えばdVDなどのような書き方は,著しく読みやすさを損なわせます.



従って,大文字で使用されているアクロニムでも,

以下のように,すべて小文字を使うか,

先頭だけを大文字にするようにしましょう.

ex)

◯: html, isUsaSpecific, checkTiffFormat()
×: hTML, isUSASpecific, checkTIFFFormat()


ルール10: 予約語や特別な名前を変数名に使わない.

MATLABは,

予約語や事前定義値を

変数名に使用すると,

よくわからないエラーメッセージや

不思議な結果を返します.

予約語は,

iskeywordという関数を使用することによって,

確認することができます.

また,事前定義値はMATLABのドキュメントに書いてあります.

MyEnigma Supporters

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

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

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

myenigma.hatenablog.com