ライブラリ作成用Arduinoスタイルガイド

ArduinoスタイルでのライブラリAPIの記述方法を学びます。

LAST REVISION: 2022/11/23 23:29

これは、ArduinoスタイルでのライブラリAPIを書くためのスタイルガイドです。これらのいくつかはプロのプログラム方法に反しています。それはわかっていますが、これにより多くの初心者がArduinoを簡単に始めることができています。そのため、これらの原則を念頭に置いて、コードを書いてください。中心的な読者に対して、Arduinoライブラリをよりわかりやすくする提案があれば、議論に参加してください。

エンドユーザに親切にしてください。 プログラムしたことのない知的な人のために、APIを書いていると仮定してください。あなたが扱うコンセプトや、利用する用語や関数の明確なイメージを考えてください。

基本機能にAPIを合わせてください。 ユーザに実装の詳細を見せたくないかもしれませんが、APIが実現性に関する不正確なイメージを示したくもありません。例えば、ある設定に関して、数個の可能性しかないときには、intを引数にする関数は使わないでください。このような関数は、どんな値でも利用できることを示唆します。

ユーザが必要とするデータと機能を中心に公開する関数を構成してください。 しばしば、特定の電気モジュールに関するコマンドは多くの一般的なユーザに対して複雑になりすぎていたり、より高レベルの機能に再構築できたりします。一般的な人が何をするかを考え、それに従いAPI関数を構成してください。AdafruitのBMP085ライブラリはいい例です。readPressure()関数は、最終的な圧力を取得する必要な手順をすべて実行します。このライブラリは、通常実行される一連の関数の実行を、ユーザが必要な値を意図したフォーマットで返す、一つの高レベルコマンドにまとめます。これは低レベルのI2Cコマンドだけではなく、中間レベルの温度と圧力計算も抽象化します。また、これらの中間レベルの関数を、それらを必要とする人向けに、パブリック関数として提供しています。

十分な、普段の言葉を使ってください。 関数名や変数には簡潔すぎる言葉は使わないでください。技術用語ではなく通常の用語を使ってください。一般的に認知できる概念に関する用語を選んでください。特別な知識を前提としないでください。例えば、以下は、pwm()ではなく、analogWrite()を選んだ理由です。略語は、その用語が一般的だったり、主要な名前の場合は、利用しても問題ありません。例えば、「HTML」は比較的一般的で、「SPI」は、事実上プロトコルの名前です(「Serial-Peripheral Interface」は恐らく長すぎます)。(「Wire」は恐らく間違いで、プロトコルとしては、「TWI」や「I2C」と呼ばれています)

一般の人に対して、意味が異なる用語は避けてください。 例えば、プログラマにとって、エラーは何かが起きたことを示すものですが、一般の人には、エラーは悪いことです。

ある分野に固有の用語を使う必要があるときは、最初に、一般の人向けの説明文を一つか二つ書いてください。 より良い用語を見つける可能性もあるし、そうでなくても、ライブラリの文書化を始めたことになります。

文書を作成し、コメントしていきます。 レイヤ文書を作成するときは、コンテンツ記述用Arduinoスタイルガイドに従ってください。

確立されたコアライブラリとスタイルを使ってください。

  • 入力を読むときはread()を使い、出力を書くときはwrite()を使ってください。例えば、digitalRead()やanalogWrite()などです。
  • バイトストリームを扱うときは、StreamとPrintクラスを使ってください。ふさわしくない場合は、少なくともそれらのAPIを手本とするようにしてください。詳細は以下を参照してください。
  • ネットワークアプリケーションでは、ClientとServerクラスを基にしてください。
  • ライブラリインスタンスの初期化にはbegin()を使ってください。通常いくつかの設定が伴います。終了するにはend()を使ってください。
  • スネークケースではなく、キャメルケースの関数名を使ってください。例えば、analog_readではなく、analogReadです。あるいは、my_new_functionではなく、myNewFunctionです。可読性の観点から、Processing.orgよりこれを採用しました。

LONG_CONSTANT_NAMES_FULL_OF_CAPS(全て大文字の長い定数名)は読みづらいです。 できれば、簡潔になりすぎない範囲で、簡略化してください。

ブール値の引数は避けてください。 代わりに、それらを説明する名前で、異なる二つの関数を提供することを考えてください。

ポインタの知識を前提としないでください。 C言語の初心者にはこれが最大の障壁となり、&と*に混乱します。このため、APIにこれらを使わなくていい場合は、いつもそうしてください。例えば一つの手段として、参照渡しをする際に、*記法ではなく、配列記法を使うことです。

1

void printArray(char* array);

は、以下のように置き換えられます。

1

void printArray(char[] array);

const charの構造体を使ったポインタを渡すライブラリもありますが、それらをユーザに要求することは避けてください。例えば、以下ではなく、

1

foo.readAccel(&x, &y, &z);

以下を使ってください。

1
2
3

xAxis = adxl.readX();
yAxis = adxl.readY();
zAxis = adxl.readZ();

シリアル通信を使うときは、Serialをハードコードしないで、ユーザがStreamオブジェクトを指定できるようにしてください。これにより、複数のシリアルポートがあるボード(例えばMega)の全てのシリアルポートに互換性ができ、SoftwareSerialのような他のインターフェイスも使うことができるようになります。ストリームオブジェクトはライブラリのコンストラクタやbegin()関数に、ポインタではなく参照として、渡すことができます。この方法の例は、Firmata 2.3やXBee 0.4を参照してください。

バイトストリーム通信を提供するライブラリを書くときは、ArduinoのStreamクラスを継承してください。これにより、Streamオブジェクトを受け付ける他の全てのライブラリで、あなたのライブラリが利用できるようになります。できれば、入力データをバッファリングしてください。そうすることで、read()はデータの到着を待たずに、バッファにすぐにアクセスすることができます。できれば、write()メソッドでは、データを送信バッファに格納してください。しかし、全ての送信データを格納するだけの十分なバッファがない場合は、write()は待つ必要があります。待つ場合は、yield()関数を呼ぶべきです。

模範となるAdafruitのいくつかのライブラリがあります。Adafruitは、デバイスの機能を高レベル機能に、非常に巧みに分解しています。

これは、Wire(I2C)ライブラリからうまく抽象化しています。 https://github.com/adafruit/RTClib

Arduinoリファレンスのテキストは、Creative Commons Attribution-ShareAlike 3.0 Licenseのライセンスを適用しています。リファレンス内のコード例は、パブリックドメインとしてリリースしています。

オリジナルのページ

https://docs.arduino.cc/learn/contributions/arduino-library-style-guide

最終更新日

December 4, 2022

inserted by FC2 system