VBAと日々のこぼれ話

  1. その他言語

【各種言語】ソース中のコメントにおける私見

前提:会社、プロジェクト、システム等々によって厳密にコーディングルールが決められていることもありますので、その場合はそちらに従うのが正しいです。

コメントの入れ方でプログラマーの技量が分かるとも言われており、コーディング技術以上に高いスキルが必要だと感じます。

コードに関しては何冊も技術書が出版されていたり、Webに情報が公開されていますがコメントについては「適宜コメントを入れる」くらいの解説が殆どというのが私の感覚です。

こればかりは、勘どころというか、学習よりも経験がものを言ってくる分野でもあるかと思います。

適宜ってどのくらいなのか

コメントが不必要で必要な理由

結論は一緒「ヒューマンエラーを防ぐため」

プログラムに影響しないのがコメントです。
ただプログラムを作っている人間に多大なる影響を与え、結果としてプログラムに影響を与えるのもまたコメントです。

だから「適宜」必要です。

コメントが不必要だという理由

コメントは嘘をつく

コメントできっちりと処理の説明がしてあるとそれが正しいものだと思い込みがち(時間がないときは特に)です。しかしその実、メンテナンスされていない事も多々あります。そもそも初めから間違った内容が書かれてあっても処理には影響がないので、コード作成者自身が気が付かないまま人の手に渡ることがあります。

第三者は、コードを読むよりもコメントの説明がまず目に留まります。

そしてそれが正しそうな雰囲気を出していたら「そうだ」と思い込んでしまいがちです。それっぽい説明文調ならなおさらです。

コメントは惑わす

コード一行にコメント一行という極端なものは少ないでしょうが、冗長的なプログラムは敬遠されます。
だって、縦長も横長も言語によらず、単純に読みにくいでしょう。

コメントが必要だという理由

コメントは注意を促す

やっていることは割と簡単にも関わらず、時にものすごく複雑な動きや普段とは違った動きをするプログラムというのがあります。

それはコメントでその理由をコメントしておくべきです。

そもそもメンテナンス面からトリッキーなコーディングをするなという話もあるのですが、そうも言ってられない場面というのもあります。

【スポンサーリンク】



書くべきではないコメントとは

『何をコメントすべきか』は時と場合によって違います。
けれど『何をコメントとして入れるべきではないか』は大体似たり寄ったりなので、私が考える不要コメントを挙げてみます。
※随時、更新予定

改訂履歴

ドキュメント(設計書)を作成しているプログラムであれば、そちらにも修正も入るでしょうしそこで履歴を一括管理すべきです。そもそも履歴管理は、バージョン管理システムの守備範囲です。

ドキュメントの全くないプログラムは、初めはメモベースでも構わないので新規で作ってそこで管理してはどうでしょうか。

修正前ソース

ソースの冗長化が促されるだけなのでやめましょう。
こういった履歴管理は、先ほども言った通りバージョン管理システムの守備範囲です。

どうしても残しておきたいなら修正前のプログラムを丸ごとコピーするのはどうでしょうか。

変数の説明

変数名自体を工夫すべきです。

「tmp」や「tmp2」といった風に場当たり的に付けるからコメントが必要になるのです。
例えば犬種、猫種を入れる変数なら「dkind」「ckind」、「dogkind」「catkind」、「kenshu」「nekoshu」(「byoshu」?)等にしておけば、わざわざ変数の説明用のコメントを入れる必要はないです。

気の利いた変数名は、プログラマーの腕の見せ所です。

処理の途中

このブログでは、説明のためにコメント多めでサンプルコードにコメントしています。
ですが、本来であればほぼコメントなしで私はコーディングします。

勿論、ソースの途中は意図を伝えないといけないトリッキーな処理にはコメントが必要です。

自分さえ読めればよいコードは自分専用であれば別に構いません。
けれどプログラマーであれば、ある程度の人がすらすらっと読めるようなコード=より良いプログラムを目指して然るべきのように思います。

何が良いプログラムなのか。

考え方は色々あるでしょうが、まず第一には、要求通りに処理をこなすプログラムだと思います。
そしてその先を目指そうとすると処理速度や保守性の高さ等が発生してきます。
その目指す先を手助けしてくれるのが可読性の高いコードだと私は思います。

可読性が高いということは、イコール、わかりやすい、よってコメントは不要という考え方です。

ですのでプログラム畑の人を以てしても『コードが読みづらい』と言われるのであれば、それは私の技術がまだまだであることが大きな要因だと思っています。

ちょっとお説教ぽくなってしまいました。

その代わりと言っては何ですが、処理の概要を「処理単位のヘッダ部分にまとめて書く」ようにしています。

どんなに長くても5行以内(大体3行くらい)でしょうか。VBAだとプロシージャ単位と言ったら分かりやすいかな。

これも賛否両論あるのですが、コメントなしを追求していたらあまりにもなさすぎるのは逆に見づらいという意見をもらったからです。ありすぎてもなさすぎても見づらいと言われるとは。難しいですね。

ちなみに一箇所で管理するのは、保守の観点からも扱いやすいからです。

その他言語の最近記事

  1. 【各種言語】ソース中のコメントにおける私見

関連記事

【スポンサーリンク】




PAGE TOP