ライブラリを設計するとき、どのガイドラインに従う必要がありますか?


11

私はUnoを使用してArduinoプロジェクトに取り組んでいます。プロジェクトには大量のコードが含まれています。ライブラリを作成し、後で共有することもできます。ライブラリを設計するとき、どのガイドラインに従う必要がありますか?


これは一般的な質問ではなく、おそらくStack Overflowの場合ではありません。とは言っても、Arduinoのメモリ制約に関する有用なヒントが得られる可能性があります。

回答:


12

ライブラリを設計する際に留意すべき点がたくさんあります。おそらく、最終的に他の人と作業を共有することになりますが、一貫した設計パターンに従うことが非常に重要です。他のユーザーのスキルレベルは非常に異なるため、使いやすいライブラリを可能な限り設計してください。

基本的なヒント

ピンマップ

ライブラリが期待する基本的なピンマップを提供します。ピンマッピングを静的にしないでください。ただし、ユーザーが簡単に変更できるようにします。

ワーキングライブラリー

最初に確認すべきことの1つは、ライブラリが機能していることです。そうでない場合は、明記してください。壊れたソフトウェアで作業しようとして時間を無駄にしたくないので、他の人もそうさせないでください。

基本的なReadme

ライブラリが設計されたボード、テストされたボード、および動作するボードを明確に述べてください。ここに記載されているすべてのボードの世代(バージョン)を指定します。

インターフェース

次に、明確に定義されたインターフェースが必要です。複雑なインターフェースを備えた作業ライブラリは、イライラさせられます。これにより、後で自分でライブラリを使用するのに役立ち、他のユーザーにとっても使いやすくなります。これは、覚えておくべき最も重要な側面の1つです。

トップダウンまたはボトムアップのどちらのアプローチを採用する場合でも、インターフェイスは常に頭の中ではっきりしている必要があります。ボトムアップのアプローチでは、これは難しい場合がありますが、無視すべきではありません。そうしないと、使用できない可能性のある非常に複雑なライブラリになります。

特殊機能

いくつかの特別なボード特性を使用する機能がある場合は、これらの機能を目立たせて、readmeとコメントにも明記してください。

忙しい待機

ビジー待機を使用する必要があるシナリオがあります。そのような機能は、プログラムロジックによっては、通常の制御フローを妨げ、重要なタスクの最中に問題を引き起こす可能性があります。可能であれば、割り込みまたは他のアルゴリズムを使用してください。そうでない場合は、そのような機能にマークを付けてください。

コメント

行ったすべての小さな変更と大きな変更には必ずコメントを付けてください。すべての重要な機能については長めのコメントを、他の機能については小さいものを書いてください。インターフェイス、各引数、その機能、および返すものを明示的に記述します。これは多くの余分な作業ですが、あなたと他の人の両方にとって非常に役立ちます。異なるボード間で機能しない可能性のある機能がある場合は、ここで言及してください。これらが他の関数によって使用されている中間関数であり、必要な場合は、Readmeに記載してください。

一貫性

コメントも含め、すべてがファイル.h.cppファイル全体で一貫していることを確認してください。

関連する機能のみを単一のファイルに保存します。いくつかの小さいながらも論理的に一貫したモジュールは、すべてが含まれる1つの巨大なファイルよりも優れています。


高度なヒント

詳細なReadme

ライブラリ、その機能、問題やバグ、基本的な使いやすさを説明した明確なreadmeファイルを作成します。上記の各インターフェイスを定義および説明するために、個別のファイルを使用します。

ディレクトリ構造

ライブラリが大きくなったら、ディレクトリに分割する必要があります。を使用している場合、これは簡単には不可能です。ただし、ここまで到達した場合は、おそらくArduinoの上級ユーザーであり、より強力な開発ツールを使用しています。そうでない場合、これはそうするように言っている宇宙です。

免許

必ずライセンスを追加してください。

バージョン管理

GitやSVNなどのVCSツールを使用します。これにより、行われた変更の確認、古いバージョンへの復帰、エラーの原因となっているコードの特定、さらに他のユーザーとの共同作業がはるかに簡単になります。


ピンマップとは何ですか?
クリスアンダーソン

2

AshRjの答えはとても良いです-それに追加するのはたった2ポイントです。

ポイント1:ドキュメント

AshRjは詳細なreadmeを書くことを推奨しました。これは良い習慣ですが、大きなライブラリではすぐに手に負えなくなる可能性があります-実際、数千行でも(実際にはそれほどではありません)、readmeにはほとんど利点がありません。私の推奨事項は、さらに一歩進んでC ++のJavadocに相当するものを使用することです- この回答で説明しているように(スタックオーバーフローについて)、Doxygenはドキュメントを管理しやすくするための非常に便利なツールです(誰も編集したくない10K行のREADMEファイル...)

ポイント2:ディレクトリ

AshRjの答えとは対照的に、常にディレクトリ使用します。たとえファイルが10個しかない場合でも、たぶん7個または8個であっても、少し馬鹿げているように聞こえますが、作業を将来にわたって保証するものです。ファイル。ディレクトリは、大規模なプロジェクトだけのものではありません。小さなプロジェクトでも使用する必要があります。C ++(事実上のArduino言語)では、ディレクトリがライブラリからファイルをインクルードする際に無視されることを覚えておいてください-それらはコード管理ツールとしてのみ存在します。

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.