たぶん即席で導入できるコーディング規約
どういう規約？
- コメントアウトは Doxygen 準拠
- または、それに準ずるもの。例えば:
- Python では Docstring (Google スタイル)
- JavaScript では JSDoc
- または、それに準ずるもの。例えば:
- 変数や関数の命名は Rust 公式 (RFC 430) に準拠
Doxygen とは
コメントアウトの書き方で迷ったことは、一度はあるのではないでしょうか。
Doxygen は、指定の規則に沿って書かれたコメントアウトから、そのプログラムのドキュメントを作れるツールです (同様のツールは他にも)。これは、コメントアウトの書き方の統一に利用することもできます。
C/C++ での書き方を例にすると、以下が Doxygen 準拠の書き方の例になります。
/**
* @brief Do anything
*
* @param[in] cnt Count of anything
* @returns Success: 0, Failed: 1
*/
int any_function(int cnt) { /*...*/ }
@... と書いてあるのが、Doxygen のコマンドです。上の例では、関数の概要、引数、返り値が示されています。もちろん関数に限らず、変数、クラス、ソースファイル本体についても説明を書くことができます。
他のコマンドについては、公式で以下のページにまとめられています。
Rust公式の命名規則 (RFC 430) とは
変数名や関数名のつけ方で、大文字区切りとアンダースコア区切りとで、どっちに統一するかで迷ったことがある人も多いのではないでしょうか。
Rust 言語では、関数や変数の名前について、大文字区切りにするか、アンダースコア区切りにするか等が規定されています。
オススメする理由
大勢の人が使っているから。 それに伴い、「とりあえず調べてみて」ができるから。
ローカルルールを策定しようとすると、
- 身内でドキュメントを整備しないといけない
- どういう書式にするかを考えないといけない
- どういったケースがあるかを考えないといけない
- カバーしきれないケースが出たときは見直さないといけない
という大変さがあります。
Doxygen や RFC 430 は多くの人が使っているため、調べればすぐにチートシートや解説が山ほど出てきます。それに有志らによるツールもあります。
どのタグを使うかなどは最終的にローカルルールの規定となりますが、ゼロから書式を考えるのに比べればずっと楽でしょう。
使えるシチュエーション
- ほぼゼロから何かを作り初め、また短期間 (1年も及ばない) で成果を上げる活動であるとき
- 学校の PBL やハッカソンとか
規約をゼロから作るのは大変ですし、そこに時間をかけてもいられません。かといって、メンバー各々のスタイルでコードを書いて、「わーお！バラエティ豊か！」というのも嫌･･･。
よく知られている規約を使うことで、準備に時間をかけずに規約を適用できます。(おまけに、有志によって洗練されたものでもある。)
逆に、使えない (使い辛い) シチュエーション
- チームで既に確立された規約がある
- 会社などで、数年に渡って動いていく組織である
大勢で、長期に渡って活動するなら、規約整備に時間を割くことも非現実的ではありません。また、Doxygen 準拠だけでカバーできない事項もあるでしょう。
まとめ
確立された規約が無ければ、Doxygen (など) や RFC 430 に従っておこう。
- 完全に皆バラバラな書き方になるよりはマシ。
- チートシートも、色々なケースもサクッと調べられるから。
- Doxygen などのツール導入は別に任意で良い。(ソースの書き方が統一できればとりあえずってことで)
最後に、ポエム的なソレのお約束。あくまでも個人の一意見として、お考えください。
Discussion