みなさん普段ソースにコメント書いてます？
私はほぼ書かないのですが。
というのもめんどくさいからとかではなくて、モダンなソースコードエディタ環境を使っていると、命名を文章チックに書いてソースを読むことが処理を読むことにつながるようにするのが可読性の点で良いと言われており、自分も実感としてそうした方が良いと感じているからです。
とはいえ全く書かないのが良いかと問われるとそんなこともないと思ってもいます。
今回は私なりのコメントの書き方を、自分ルールの備忘も兼ねてちょっと纏めてみようかなと思います。
Da★Bo流コメントルール
変更履歴は書かない
変更履歴は書きません。
足の長い開発をしていたり、開発黎明期のソースコードでこんなものを書いてしまうと、日々どんどん冒頭のコメントが長くなってしまうからです。
変更履歴は基本的にバージョン管理ツールや、プロジェクト管理システムにチケットとして残し、ソースコードには一切書きません。
ファイルヘッダコメントはちょっと書く
これは自分以外のメンバへの配慮として物に寄っては少し書きます。
具体的には基底クラス系のクラスを定義しているファイルや、
一々実装を見てほしくない複雑な処理を書いたファイルです。
例えばTCP/IPソケットプログラミングで、純粋にTCP/IPのシステムコールをラッピングしたTCP/IPベースクラスを作ってそれをクライアントとサーバのクラスに継承する場合。
”クライアントとサーバの共通部分を定義したファイルです。”
程度のコメントを残します。
関数/クラスヘッダコメントは書かない
関数やクラスのヘッダコメントは書きません。
特に私は関数は絶対20行超えないマンなので、ヘッダコメントなんて書いているとソースコードよりヘッダの分量が多くなります。
そのかわりに関数名をなるべく読めばわかるように書きます。
たとえば
u_char* allocate_buffer_to_recieve( size_t allocate_size )
とか。
変数の使われ方は書く
これまではあまり書かないという話でしたが、逆に変数にはどう使われるかを書くようにしています。
例えば
//機材からの受信データをバッファに書き込む際のロックに使用します
//バッファからデータを取り出す際のロックに使用します
std::mutex recieve_mtx;
とか。
変数の使われ方をコメントに書いておくことで、その変数を使っている処理を読み解く際のヒントにもなります。
特にC/C++での開発経験の浅い方はやもすれば処理に書かれている構文の読み方で頭が一杯になっている場合が多いので、この変数はこういうことに使われているんだよ〜という情報があるだけで構文への理解が早まります。
まとめると
大量に書いても切りがないので、大きくはこの辺が私ルールです。
基本的には「命名を英語の文章として読めばコメントなくてもわかるだろ」、な私ですが、チームで開発や、経験の浅い方への教育をする上ではここに書いたようなルールをなるべく徹底することで周囲のメンバーとの協調を図っています。
もしコメントを大量に書いてしまって読みにくい、けどどのポイントに絞って書けばいいかわからない、という方のご参考になればと思います。
投稿
0 件のコメント:
コメントを投稿