MyEnigma

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

MATLAB Programming Style Guidelines 4: Functions

この記事は,

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

深く感謝します.


Functions

関数の名前は,その関数のそのものを語るものでなければなりません.


ルール1: 関数の名前はすべて小文字で記述する.

関数名だけでなく,m-fileの名前もすべて小文字で記述するようにしましょう.

小文字で書くことにより,

複数のOS環境で生じ得るファイル名のエラー問題を防ぐことができるのです.

関数名の例: getname(.), computetotalwidth(.)




この関数名の記述方法以外にも,

一般的に使用されている方法が2つあります.

一つは,アンダースコアを使って

読みやすい名前を記述する方法.

2つ目は,変数名と同じルールで関数名も決定する方法です.

しかし,このガイドラインでは,

関数名はすべて小文字で記述方法を推薦します.



ルール2: 関数名は意味を成す名前にすべきです.

MATLABには,短い関数名を使用したり,

よくわからない関数名を使ってしまうことを助長してしまう

理由があります.

それは,文字数の制限です*1

しかし,関数の読みやすさを向上させるためには,

きちんと読むことができるように名前を記述すべきです.

ex) ◯: computetotalwidth() ×:compwid()



しかし,数学などで一般的に使用されている略語やアクロニムなどは例外です.

ex) max(.), gcd(.)*2




このような短い名前の関数の場合,

一番最初のコメントヘッダに略語やアクロニムではない

元の言葉を書くべきです.

これをすることにより,ユーザがその関数を理解しやすくなり,

lookfor関数を使った時に,その関数の検索性を向上させることができます.


ルール3: 単一のアウトプットする関数の名前は,そのアウトプットの名前にする.

これはMath Worksのコードでは一般的に適用されているルールです.

ex): mean(.), standarderror(.)


ルール4: 返り値がない関数や,ハンドルのみを返す関数の名前は,その関数が行うことを名前にする.

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

同様に,その関数が何をすべきで,なにをすべきでないのかも知ることができます.

これによって,意図しない問題が生じることを防ぐことが可能になります.


ex) plot(.)


ルール5: getやsetが前についた関数は,オブジェクトにアクセスしたり,プロパティを設定する関数にする.

これはMath Worksはもとより,

C++やJavaの開発においても,一般的なルールです.

ex) getobj(.); setappdata(.)



ルール6: computeというプレフィックスは,何かを計算する関数に使用する.

このようにcomputeのプレフィックスを一貫して使用することは,

コードの可読性を高めます.

これにより,コードの読者に

この関数は複雑であり,計算時間を必要とすることを

知らせることができます.

ex) computweightedaverage(); computespread()


ルール7: findというプレフィックスは,何かを検索する関数に使用する.

これにより,この関数の使用者は

この関数は単純な検索関数であることを理解し,

計算時間もそこまで必要としないことを知ることになります.

このようにfindのプレフィックスを一貫して使用することは,

コードの可読性を高めます.

ex) findoldestrecord(.); findheaviestelement(.);



ルール8: initializeというプレフィックスは,オブジェクトを生成する関数に使用する.

イギリス英語の"initialise"とアメリカ英語の"initialize"があるが,

アメリカ英語の"initialize"を使用すべきでしょう.

"init"と省略することも,控えるべきです.

ex) initializeproblemstate(.);



ルール9: isというプレフィックスは,ブール関数に使用する.

これは,MathWorksやC++,Javaでよく使用されているルールです.

ex) isoverpriced(.); iscomplete(.)



しかし,あるブール関数ではisよりも,

その関数の内容をより適切に表現するために,

より適切なプレフィックスを使うべき時もあります.

ex) hasLicense(.); canEvaluate(.); shouldSort(.);


ルール10: 互いに補完し合うオペレーションをする関数には,補完し合う名前を付ける.

対称的な名前を付けることで,

関数名の複雑性を減らすことができます.



ex) 補完し合う名前の例(プレフィックスとして使う)

get/set, add/remove, create/destroy, start/stop, insert/delete,

increment/decrement, old/new, begin/end, first/last, up/down,

min/max, next/previous, old/new, open/close, show/hide,

suspend/resume, etc.


ルール11: 意図しない同一名の関数群は作らない.

一般的に,関数の名前はそれぞれユニークであるべきです.

Shadowing(複数の関数が,同じ名前を持つこと)は

コードの意図しない振る舞いや,エラーを誘発させます.


関数名が重複しているかどうかは,which -all や existコマンドでチェックすることができます.

MyEnigma Supporters

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

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

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

myenigma.hatenablog.com

*1:現在のMATLABでは31文字まで大丈夫なようです.

*2:the greatest common divisor《数学》最大公約数