本記事は、コーディングする時に、「コメントする？しない？」という議論について投稿者の考えを綴った記事になります。

以前の記事(可読性について)で、リーダブルコードの内容をまとめた時に、コメントを「残すべきこと」とコメントを「すべきでない」ことについて記述しておりましたが、今回はその深堀をしていきたいと思います。

はじめに

まず投稿者の考えの大前提として、「絶対にこれが正しい」はないと思っています。

その現場によって それぞれベストが違う からです。

ただ、コメントを「残す」か「残さないか」で議論になった時に、
1つの考え方の基準になればなと思います。

コメントを残すことのメリットについて

投稿者自身、コメントを残すことは自体は肯定的です。

コメントを残すことで、以下のメリットがあると感じているからです。

• 書き手の意図を読み手に知らせる
• コードを書いている本人の頭の中の大切な情報を、読み手に伝えることができる
• コードからは読み取れない「背景」や「経緯」を読み手に伝えることができる

大きなプロジェクトになればなるほどこれらの恩恵は大きく、
新規メンバーもキャッチアップしやすくなります。

ただし、なんでもかんでも全てコメントを残すべきか？と問われると、
わかりきっていることに対してのコメントは逆に可読性を下げるだけ です。

なので、「その前にやるべきことがちゃんとできているか」という観点が必要だと思います。

コメントを残す前にやるべきこととは？

では、コメントを残す前にやるべきこととは何か？ですが、
投稿者が思う「やるべきこと」は以下の通りです。

• 適切な命名がなされているか
• 命名以上の責務を行なっていないか
  • 命名で悩んでしまう場合、正しい責務でないケースが多々あります
• ループとロジックが単純化されているか

つまり、 大前提として コード自体が読みやすいこと であり、
ひどいコードを補うためのコメント は コード自体をみなおそう ということです。

不吉なにおいのするコードはプロジェクト全体をゆっくりと腐らせていく

いわゆる 不吉なにおい のするコードを残したまま、
コメントで補うことは本末転倒でありプロジェクト全体をゆっくりと腐らせてしまいます。

• ロジックが複雑すぎてバグの温床となる
• 機能拡張しようとすると至る箇所でバグが発生してしまう
• 新規メンバーが安易に触れないコードになってしまう

上記のような地獄の連鎖が始まってしまいます。

テストコードがあればまだましですが、
なければストレスフルな日々があなたの目の前にやってくることでしょう。

そうならないためにも、
日頃からより良いコードを書いて積み上げる必要があります。

リーダブルコードのススメ

では、良いコードとは？ですが細かくあげるとキリがないので、
まずは「リーダブルコード」をオススメいたします。

投稿者の思いとして、
プログラミングをされるのであれば全員に熟読して頂きたい書籍です。

内容としては初歩的な内容なのですが、
プログラミングする上で大切なエッセンスが詰まっています。

最後に

以上、投稿者のコメントに対する所感を述べさせて頂きました。

冒頭にて申しましたがそれぞれのベストがあると思いますので、
あくまで1つの観点として受け止めていただければと思います。

ご拝読ありがとうございました。