より使ってもらいやすいコンポーネント・ライブラリにするためには

Page last updated 21 Aug 2015, by Tedd OKANO. 0 replies

Information

ここに書いたものは，とあるグループで「公開するコンポーネント・ライブラリに一定以上の品質を持たせよう」という議論があり，「ではどんな基準があればそれを実現できるか」という個人的な意見をメモとしてまとめたものです．

  • mbed-SDKのコーディングスタイル(日本語版)にできるだけ合わせる．
    (このリンクの『ルール』の項目はかなり厳密に感じられます．が，基本的には次の「Format Code」が行われていれば，ライブラリについては問題無いと思います)
    • オンラインコンパイラを使っているなら，公開前に「Format Code」ボタンを押しましょう． これによりインデントのスペース挿入，カッコの扱いなどがコーディングスタイルに合わせて自動的に整形されます．
    • ライブラリAPI部分のクラスや関数，変数の命名規則もこのスタイルに合わせましょう(下記の項目は小野寺さんのメモからの抜粋)
      1. クラス名は大文字で始める(途中小文字や大文字を使ってもかまわない)
      2. メソッド(関数)名は小文字で始める(途中小文字や大文字を使ってもかまわない)
        (ただしコンストラクタはクラス名と同じにしなければならないため大文字で始める)
      3. 変数名は小文字で始める(途中小文字や大文字を使ってもかまわない)
      4. 定数名はすべて大文字
    • ライブラリ内部(アプリケーションからはアクセスされない部分)については特に規定しない(他から移植してくる場合，これも直すと大変なので)
  • APIドキュメントを書くようにしましょう
    • APIドキュメントはクラスの.hファイルにコメントとして書いておきます．「API Documentation」のページを参照
    • Doxygenというフォーマットに則った方法で記述します．これを書いておくとライブラリの解説が自動生成されます．公開ページなどで関数や定数などの説明を行うページが自動で作られます
    • とりあえず日本語で構いません
  • プログラムそのものに関して
    • あまり作り込み過ぎないようにしましょう．フル機能のマニアックなライブラリより，手軽に使えるライブラリのほうが価値があるでしょう．もし手軽版で不足があれば，その目的に合った機能を補うコードを誰かが書けばいいのですから．
    • 「浮動小数型は使わないほうが良い？」という議論があります．確かに組み込み系で，今後そのライブラリを非力なマイコンに移植することを前提とするなら，使いたくないと考えるのが普通です．
      しかしたとえば，PWM出力のデューティ比を0.0〜1.0までの正規化した値で与えたり，温度センサからは小数点付きの摂氏温度の値がが得られるのはmbedの真骨頂(のひとつ)であると思います．これによってアクセスするレジスタのビット数などを考えなくても直感的に値を扱えるようになります．
      というわけで，ここで一つ提案を．移植などを前提に作られるライブラリの場合，mbedインターフェース部だけ切り離せるように作っておくのはどうでしょう？関数の多重定義(オーバーロード：引数や返り値の方の違いによる，複数の同名関数の定義)を使ったり，あるいはそれでは不便な場合はベースとなるクラスを整数型のみで実装しておき，mbed向けには継承したクラスで関数を差し替えてしまうような方法が取れると思います．
    • 上記の点は「より高いレベルでの，ハードウェアの隠蔽(抽象化)を行う手段として有効」とも言い換えることができるかもしれません
  • 作ったら公開してコンポーネント登録しましょう
    • コンポーネント登録に必要な項目を埋めると，ユーザが必要とするピン配置やデータシートの情報もここに纏まることになります．
  • テストの協力者を募りましょう
    • 公開したコードは沢山のプラットフォームで動いたほうがいいですよね？なので誰か試してくれるヒトを探しましょう．
    • もし可能ならハードウェアの提供，または貸出を行って，動作に問題ないかを確認してもらいましょう．
    • 動作確認をしてあげたヒトは，コンポーネントページの「Tested platforms」欄の追加をしてあげましょう．
    • コードの問題(バグfix，コメント修正)を解決した場合にはプルリクエストを出しましょう．受けた側はコードをマージして公開しましょう．
  • オープンに話をしましょう
    • フォーラムやQ&Aなどを利用してオープンに話しをしましょう．公開されているライブラリの改良案や良いアイデアが浮かんだ時など
    • (だれでも参加しやすい雰囲気作りを心がけましょう)

「トラ技_mbedライブラリの作成方法の勉強会」資料

http://developer.mbed.org/users/okano/notebook/mbed-library-study-meeting-2014-nov-07/

Please log in to post comments.