スネークかキャメルかパスカルか

2024年7月21日 07:35

Meridian計画。
細々としたところを細々とリファクタリング中です。
コマゴマとしたところをホソボソと修正しています。

コードをChatGPTに評価させながら一般的ではない箇所を修正していますが、スネークケースとキャメルケースの混在を指摘されたので、変数や関数などの命名規則についてあらためて調べてみました。

メジャーな命名規則

命名時の大文字小文字などの使い方について、以下のタイプがあるそうです。

スネークケース (snake_case)

単語をアンダースコア（_）で区切る形式。
Python、Ruby、C言語など。

キャメルケース (camelCase)

最初の単語は小文字、続く単語の先頭文字を大文字にする形式。JavaScript、Java、C#など。

パスカルケース (PascalCase)

すべての単語の先頭文字を大文字にする形式。
C#、Delphi、Javaなどのクラス名やタイプ名。

ケバブケース (kebab-case)

単語をハイフン（-）で区切る形式。
URLのパスやCSSクラス名。

ほかにもいくつかあるようですが、概ねこんな感じです。（他にはアンダーバーを先頭や末尾につけるルールなどがあります。）

Meridian計画はより多くの人に使ってもらいたいと考えているので、基本的にはながいものには巻かれろで進めていきます。
PythonやC++、ROSなどでもよく見慣れたスネークケースに巻かれたいと思いますが、単純にスネークに統一してしまうと、かえって可読性を下げるような気もします。

まぜて使ってはダメなのか？

実際にコードを書いていくと、たとえば変数名をスネークで統一しようとした場合、クラスや構造体名はキャメルやパスカルで書いた方が直感的に違いがわかりやすく、見た目にもしっくりくる気がします。
そこで、混ぜてうまくいっているケースがあるかを調べてみました。

世の中にはコードの「ガイドライン」というものがいくつか存在するようです。いくつか存在する時点で、思想の違いやイデオロギー論争を巻き起こしそうでちょっとドキドキします。
Google C++ Style Guide, C++ Core Guidelines, LLVM Coding Standards, Mozilla Coding Style Guide, Chromium C++ Style Guide, Microsoft C++ Guidelines, MISRA C++ Guidelines, Facebook C++ Style Guide, JSF++ AVなどです。

とくにメジャーなものがGoogle C++ Style GuideとC++ Core Guidelinesのようです。

異なる規則の組み合わせ方法として、

クラス名、構造体名、型エイリアス名：PascalCase
変数名：snake_case

という組み合わせを、Google C++では推奨し、C++ Coreでも許容しているようです。ほかにも LLVM, Mozilla, Chromiumなどでもこの書式はOKのようです。
そんなメジャーなガイドラインが採用しているのであれば、ケースを混在させることは問題なさそうです。読みやすく感じますので、Meridian計画でもこの方式を採用したいと思います。

関数名やメソッドはどうする？

関数名やメソッド名はどうでしょうか。
各ガイドラインのルールを表にまとめてみました。

関数名やメソッド名はどのタイプもありえそうです。
ROS本の関数やメソッドはスネークの場合が多いような気がするので、GoogleやC++Coreとはズレてしまいますが、snake_caseを基本としようと思います。

ということで現時点では、当Meridain計画では
クラス名、構造体名、型エイリアス名：PascalCase
変数名：snake_case
関数名、メソッド名：snake_case
としたいと思います。

ドキュメンテーションコメントの書式は？

関数などの上につける解説文の書式についても決めておこうと思います。
ドキュメンテーションコメントにもいくつか定石のフォーマットがあるようです。
ブロックコメント方式というのがメジャーなようで、

/**
 * @brief 関数の説明
 * 詳細な明文
 * @param パラメータの説明
 * @return 戻り値の説明
 */

という書式になります。ドキュメントを生成するツールであるDoxygenと互換性があり、Doxygen形式とも呼ばれるようです。
"/*" と "*/" で囲んだ部分が全行コメントアウトとなる機能を利用しており、"/** … */"と囲みます。

ただしこの方法だと、コードをたとえば全行ごっそりコメントアウトしたい時に、その "/* … */" と競合します。全行コメントアウトしようとしても、途中にあるドキュメンテーション用の*/ に反応してコメントアウト範囲がそこで終わってしまいます。

その競合を避けることができるのが下記の書式です。

/// @brief 関数の説明
/// @param パラメータの説明
/// @return 戻り値の説明
bool test_func(int x){
//(関数処理)
return true;
}

この方式はシングルラインコメント方式と呼ばれ、Doxygenでちゃんと認識してくれるそうです。
Meridian計画では以下のドキュメンテーションコメント方式としてシングルラインコメント方式を採用したいと思います。

タグは基本的に以下のものを使うようにしようします。
@brief: 簡潔な説明。
@param: パラメータの説明。
@return: 戻り値の説明。
@details: 詳細な説明。
おまけとして、下記も使って良いと思います。
@note: 注釈。@warning: 警告。 @see: 関連する項目への参照。

まとめ

Meridian計画で採用する書式は、

変数名、関数名、メソッド名は、snake_case
クラス名、構造体名、型エイリアス名は、PascalCase
ドキュメンテーションコメントは、シングルラインコメント方式。

としてみます。…少なくとも現時点では。

その前にフィロソフィーを明示すべきかも

今回のようになんらかのキメが必要な部分では、Meridianの開発思想に照らし合わせて決めていますが、その開発思想が明文化されているかというとちょっと怪しいです。rosjpの発表などでも語ったような気もしますが、はっきりとは宣言できていなかった気もします。
本格的な共同開発が始まる前には、そのあたりもまとめておこうと思います。