回答:
ライブラリを設計する際に留意すべき点がたくさんあります。おそらく、最終的に他の人と作業を共有することになりますが、一貫した設計パターンに従うことが非常に重要です。他のユーザーのスキルレベルは非常に異なるため、使いやすいライブラリを可能な限り設計してください。
ライブラリが期待する基本的なピンマップを提供します。ピンマッピングを静的にしないでください。ただし、ユーザーが簡単に変更できるようにします。
最初に確認すべきことの1つは、ライブラリが機能していることです。そうでない場合は、明記してください。壊れたソフトウェアで作業しようとして時間を無駄にしたくないので、他の人もそうさせないでください。
ライブラリが設計されたボード、テストされたボード、および動作するボードを明確に述べてください。ここに記載されているすべてのボードの世代(バージョン)を指定します。
次に、明確に定義されたインターフェースが必要です。複雑なインターフェースを備えた作業ライブラリは、イライラさせられます。これにより、後で自分でライブラリを使用するのに役立ち、他のユーザーにとっても使いやすくなります。これは、覚えておくべき最も重要な側面の1つです。
トップダウンまたはボトムアップのどちらのアプローチを採用する場合でも、インターフェイスは常に頭の中ではっきりしている必要があります。ボトムアップのアプローチでは、これは難しい場合がありますが、無視すべきではありません。そうしないと、使用できない可能性のある非常に複雑なライブラリになります。
いくつかの特別なボード特性を使用する機能がある場合は、これらの機能を目立たせて、readmeとコメントにも明記してください。
ビジー待機を使用する必要があるシナリオがあります。そのような機能は、プログラムロジックによっては、通常の制御フローを妨げ、重要なタスクの最中に問題を引き起こす可能性があります。可能であれば、割り込みまたは他のアルゴリズムを使用してください。そうでない場合は、そのような機能にマークを付けてください。
行ったすべての小さな変更と大きな変更には必ずコメントを付けてください。すべての重要な機能については長めのコメントを、他の機能については小さいものを書いてください。インターフェイス、各引数、その機能、および返すものを明示的に記述します。これは多くの余分な作業ですが、あなたと他の人の両方にとって非常に役立ちます。異なるボード間で機能しない可能性のある機能がある場合は、ここで言及してください。これらが他の関数によって使用されている中間関数であり、必要な場合は、Readmeに記載してください。
コメントも含め、すべてがファイル.h
と.cpp
ファイル全体で一貫していることを確認してください。
関連する機能のみを単一のファイルに保存します。いくつかの小さいながらも論理的に一貫したモジュールは、すべてが含まれる1つの巨大なファイルよりも優れています。
ライブラリ、その機能、問題やバグ、基本的な使いやすさを説明した明確なreadmeファイルを作成します。上記の各インターフェイスを定義および説明するために、個別のファイルを使用します。
ライブラリが大きくなったら、ディレクトリに分割する必要があります。arduino-ideを使用している場合、これは簡単には不可能です。ただし、ここまで到達した場合は、おそらくArduinoの上級ユーザーであり、より強力な開発ツールを使用しています。そうでない場合、これはそうするように言っている宇宙です。
必ずライセンスを追加してください。
GitやSVNなどのVCSツールを使用します。これにより、行われた変更の確認、古いバージョンへの復帰、エラーの原因となっているコードの特定、さらに他のユーザーとの共同作業がはるかに簡単になります。
AshRjの答えはとても良いです-それに追加するのはたった2ポイントです。
ポイント1:ドキュメント
AshRjは詳細なreadmeを書くことを推奨しました。これは良い習慣ですが、大きなライブラリではすぐに手に負えなくなる可能性があります-実際、数千行でも(実際にはそれほどではありません)、readmeにはほとんど利点がありません。私の推奨事項は、さらに一歩進んでC ++のJavadocに相当するものを使用することです- この回答で説明しているように(スタックオーバーフローについて)、Doxygenはドキュメントを管理しやすくするための非常に便利なツールです(誰も編集したくない10K行のREADMEファイル...)
ポイント2:ディレクトリ
AshRjの答えとは対照的に、常にディレクトリを使用します。たとえファイルが10個しかない場合でも、たぶん7個または8個であっても、少し馬鹿げているように聞こえますが、作業を将来にわたって保証するものです。ファイル。ディレクトリは、大規模なプロジェクトだけのものではありません。小さなプロジェクトでも使用する必要があります。C ++(事実上のArduino言語)では、ディレクトリがライブラリからファイルをインクルードする際に無視されることを覚えておいてください-それらはコード管理ツールとしてのみ存在します。