こんばんは。 ishturk です。 この記事は Akerun Advent calendar 2日目の記事です。
Akreun の組み込み開発ではC言語がなかなかの割合を占めています。
過去にモジュール設計の話を
で書きました。どうモジュールを分けるかはとても重要な設計タームです。
背景
さて、モジュールをうまく分割できたらそれぞれ実装します。担当者は複数かもしれません。
この記事では、分けたモジュール間のAPI仕様をチーム間でどう共有したら捗るかの一例をご紹介します。
「API仕様をチーム間でどう共有したら捗るか」です。大事なことなので2回言いました(書きました)
何を解決するか
結論
いきなり結論です
Doxygen形式で公開ヘッダファイルにコメントを記載するのがいろいろな面でシンプルで良いです。
たぶん導入しようとして挫折したPMの方もいるんじゃないでしょうか。。。多分それは、がんばりすぎたのです。
Doxygen の紹介
Doxygen形式ってなんぞや?の方ももちろん多いと思いますのでざっくり解説します。
簡単に言うと
- 記法にそった書き方をするとソースファイル・ヘッダファイルからドキュメントを自動生成してくれるツール
です。具体的には、
- 関数の入力・出力引数と意味を明示できる
- 関数の戻り値の意味を列挙できる
- enumやstructのメンバにコメントできる
他にも
- モジュール間の依存関係を視覚化してくれる
- HTML、Latex、RTF などの形式で出力できる
などなど魅力的な機能もあります。
けっこうアチコチで使われていて、僕らがお世話になっている Nordic さんの SDK API 仕様書も Doxygenで生成されていました。
https://www.nordicsemi.com/DocLib/Content/SDK_Doc/nRF5_SDK/v15-0-0/index
API仕様をチーム間でどう共有したら捗るか
本題です。
ルールを決める
単純なルールを決めます。
他の人(モジュール)から呼ばれる関数には必ず定義のすぐ上にdoxygen形式でコメントを記載する。 使う相手に伝えたいこともdoxygen形式でコメントを記載する。
ルールはこれだけです。
やってみる
僕が推奨する最低限の内容はこんな感じです。
typedef enum { SUCCESS, ///< 成功 PARAM_ERROR, ///< パラメータエラー GENERAL_ERROR, ///< その他のエラー } HogeRet; /** * @brief ほげをdoする * @param a [in] ほげの値 * @param b [out] doした結果を格納するバッファのポインタ * @retval SUCCESS 問題なし * @retval GENREAL_ERROR エラー * @note リエントラント非対応 */ HogeRet hogedo(int a, int*b); void hikoukaifunc(int c);
書き方を解説します。
enum
///< メンバのコメント
enum や struct で説明が必要な場合は書きます。
関数
ちなみに @func(関数名を書くための記法) はコメントを全然ちがう場所に書く場合に使うのですが「必ず定義のすぐ上にdoxygen形式でコメントを記載する。」とルール化すれば不要な記法です。
/**
アスタリスク2つ以上が必須です。 (過去に僕はこれで一晩悩みました)
@brief 関数の説明
関数の説明を書きます。
@param 変数名 [in/out] 説明
型は不要です。変数名から自動で判断してくれます。
@retval 値
返し得る値のリストです。書いてないものは書かない。
@note コメント
こういう使い方しないでね〜という実装ってよくあると思うんです。ここに書く。
Doxygen によるドキュメントの生成
しません (ドヤッ
どういうこと?
ここで強調したいのが 「 API仕様をチーム間でどう共有したら捗るか」(3回目)が目的であることです。
なので、十分目的は達成しています。
doxygen形式で書くことをルール化したことで
- フォーマットを世の中で使われている方法に統一する(オレオレじゃないというのが重要
- 公開ヘッダに必ず残る = ヘッダを見れば仕様がわかる
- ドキュメントを別管理しないので仕様変更しやすい(実装者がdoxygenコメントも直せばOK
という旨味があります。
また、
- API仕様作成時点でヘッダができる = スタブ実装が(ほぼ)不要
といういいこともありました。
なぜドキュメント化しないのか
ドキュメントを自動生成する運用まで設計しようとすると、ステークホルダーが増えるので、スタートしづらいと思います。ここで挫折しちゃうパターンがそこそこあるようで。
自動生成できる(はずな)ソースコードになっていれば、あとから生成することもできるので、まずはソースコードだけで運用してみてはいかがでしょうか。
実装する場合ってgrepしちゃうからドキュメント見ないんですよね。
もちろん、doxygen形式で記載していれば、doxygenコマンドをCIに組み込むだけです。その話はまたどこかで。
おわりに
API仕様をチーム間でどう共有したら捗るか をご紹介しました 。ミスコミュニケーションを撲滅して快適な組み込み開発をしましょう。
おまけ
Photosynthでは一緒にはたらく仲間を募集しております!