スペースキャメルコメントスタイル & レイヤーコメントスタイル
スペースキャメルコメントスタイル & レイヤーコメントスタイル
> for English Pages kyowg.blogspot.com
1. Overview
プロジェクトにコメントスタンダードがない場合、ソースコード上のコメントスタイルは、プログラマーのスタイルによって様々だろう。 このポストでは、プログラミングのコメントスタイルとして、スペースキャメルコメントスタイルと、レイヤーコメントスタイルを示す。
2. Introduction
プログラマーからよくこのような声を聞く。
「コメントに何を書いていいか分からない。」
「コメントの粒度が分からない。」
このポストでは、これらの解決方法の一つとして、スペースキャメルコメントスタイルと、レイヤーコメントスタイルを提示する。 尚、以下についてはこの投稿では特に触れない。
3. コメントスタイル
3-1. スペースキャメルコメントスタイル
一般的な定義が見当たらなかったため、ここでは「スペースキャメルコメントスタイル」として定義する。 このコメントスタイルは、オブジェクト指向のメソッド名のような、キャメル記法にスペースを挟んだコメントスタイルである。
# set Controllers and View Resources
このスペースキャメルコメントスタイルがなぜ有用か。 このコメントスタイルは、ロジックをメソッド化する場合の命名アプローチに似ている。 どこからどこまでの処理を「一つの振る舞い」として考えるかで、コメントの範囲が決められる。 その「振る舞い」に対して、メソッドを命名をするかのようにコメントを記述する。 こうすることで、コメントの粒度やスタイルが明確になっていく。 粒度のコツは、処理の流れを振る舞い単位で考えることだ。 可読性向上のために、シンプルな命名に慣れたトッププログラマーなら、この記法でもおそらく違和感はないだろう。 また、コメントはメソッド名のように再利用性や衝突などの影響を受けないため、メソッド名よりもはるかに柔軟に書けるはずだ。 もちろん、コメントで多くを説明しなければならない場合にはこれにあたらない。
3-2. レイヤーコメントスタイル
一般的な定義が見つからなかったため、ここでは「レイヤーコメントスタイル」として定義する。 このコメントスタイルは、マークダウンのヘッドの階層のようなコメントスタイルである。
# set Controllers and View Resources processing… ## for Controllers processing… ## for View Resources processing…
このレイヤーコメントスタイルがなぜ有用か。 プログラムソースコードは、同じレベルのインデントであっても、処理の階層が異なる場合がある。 このような場合において、コメントを多階層に考えることによって、処理の視認性やコードの可読性をあげられるかもしれない。
4. Conclusion
このポストでは、スペースキャメルコメントスタイルと、レイヤーコメントスタイルの 2 つのプログラミングのコメントスタイルを提示した。 スペースキャメルコメントスタイルについては、デプロイ時のコミット文にも応用可能かもしれない（詳細文は別）。 また、プログラミングスタイルが、オブジェクト指向でも手続き指向でも、低レイヤーの処理は必ずどこかに書かなければならない。 これらのコメントスタイルは、そういった低レイヤーの処理の記述には特に有用かもしれない。
