【プログラマー】コメントは不必要!?それはただの理想論!!

プログラマーの中で、よく議題にあがる問題。

ソースコードにコメントは書くべきか

残すべきという意見と残さなくてよいという意見、どちらも耳にしたことがあると思います。

これに関して、「理想と現実」をしっかり見極める必要があるかな、というのが私なりの考えです。

そこで、何故「理想と現実」を見極める必要があるのか、書いていこうと思います。

 

最初に結論を言っておこう

これから、コメントが必要かどうかについて色々と書いていくのですが
最初に私なりの結論を言っておきます。

「コメントは必要!ただし、不要なコメントは残すな!!」

です。

基本的には、コメントがあった方が良いと考えています。
ただし、不要なコメントはいらないです。

これが私の意見です。
 

ソースコードへのコメントとは

そもそも、ソースコードへのコメントとはどういった物でしょうか。

こちらの記事にあるソースをちょっと見てみます。

【javascript初心者用】Mathクラスの勉強に!運試しサイトの作成方法!!

この記事で、こんなコードを書きました。

  //入力された記事タイトルを取得
  var title = document.getElementById('txtTitle').value;
 //出力するオブジェクトを取得
  var out = document.getElementById('output');
  //記事タイトルの文字数を取得
  var count = title.length;

「//」

から始まるところが、コメントアウトと言われる部分ですね。

これを何故書いているのか。

ソースを読むときに、分かりやすくするため

これに尽きるかなと思います。

コードを後から自分で読んだり、他人が読む際には
コメントがあることによって、どんな動作をするコードなのか、を示すためのものですね。

これがあることで可読性が上がるので、コメントを書くように癖をつけている人も多いと思います。

 

コメントは残すべき?

じゃあ、コメントは絶対残すべきなのでは?って思いますよね?

私もそう思っていました。
だって日本語で書かれた文字の方が頭に入ってくるし、分かりやすいと思ってたから。

でも、あるべき論を考えることで、ちょっと違った見方も出来ます。

 

コードのあるべき姿

可読性の良いコード

と聞くと、みなさんどんなイメージを浮かべますか?

浮かべたイメージの中のコードでは、しっかりコメントが入っていましたか?

コメントが入っていたという方。

そのコメントを全部削除してみてください!!

その状態で、それは可読性が良いコードでしょうか?

ここまで書くと気づいたと思います。

そう。
可読性の良いソースコードのあるべき論。

「コメントがなくても、何をやっているかが理解できるコード」

ではないでしょうか?

具体的に言うと、

・メソッド名から、そのメソッドの中身が想像できる
・定数や変数を用いて、値に意味を持たせる

などなど。

コメントを残すべきという意見の方でも、もちろん気をつけている部分だとは思いますが、

あるべき姿としては、コメントがなくても可読性の良いコードがベストなのではないでしょうか。
※異論は認めます。

 

コメントは必要ない?

じゃあ、あるべき論にしたがってコメントは書かない方が良いのだなって思った方。

ちょっと待ってください。

あるべき論は、所詮あるべき論なのです。
個人的に、これはただの「理想」だと思っています。

現実問題、コメントのないコードにして良いかどうか。

これは、プロジェクトによりけり、もっと言うとチームメンバー・保守をする人次第になってくるはずです。

 




現実的に考える

あるべき論として、理想の姿を考えてみましたが、

やはり現実的に考えなければ、実際の運用としてどうするべきかは見えてこないですね。

ということで、現実的に考えていきましょう!

 

スキルレベルは絶対にバラつきがある

まずはこれ。

プログラマーのスキルレベルが、チーム内でバラつきがない。
なんてことは絶対にありません。(これまでの私の経験上)

なので、自分にとって分かりやすいコードを書いたとしても、
別の人が読んだときに、その人が分かりやすいコードだと感じるかどうか。それはまた別問題です

メソッドの命名に関しても、知識レベルによって、中身を想像する力は変わってきます。
人それぞれのバックグラウンドによっても変わってくるでしょう。

そうなんです。
結局、人によって「分かりやすいコード・読みやすいコード」なんて変わってくるのです。

それを補ってくれるのが「コメント」ではないでしょうか。

 

コードとコメントの両方から判断が出来る

コメントを残さなくても、分かりやすいコードを書く。

これは、コメントを残す残さないに関わらず、実践すべき内容だと思います。

ただ、人間がコードを読むとき。

コードを読みつつ、コメントからも判断をして読み進めていくことが出来ます。
コンピューターじゃないんだから、複合的に判断をして読むことが出来るんです。

複合的に判断をする。

ということは、コメントは残せば良いって物でもないことが分かるかと思います。

無駄に長いコメントが書かれていたり、各行毎にコメントがあったりすると

コード自体を読みたいときに、コメントが邪魔になってしまうこともあります。

なので、コメントは残すべきだけど、

無駄なコメントは書かない!!

これも大事なポイントでしょう。

 

会社員としてのプログラマー

最後にこれ。

会社員として、プログラマーをしている方々。

納期」ってありますよね?

いくら分かりやすい・読みやすいコードを書くべきだとは言え、
「納期」が決められている中で、開発を進めていく必要があると思います。

そう。時間的制約がある中で、全員が分かりやすいコードのみで書くなんて、中々ハードルが高いのです。

ということで、難しいロジックを書くときには、コメントを書いて理解の助けとなるものを残しておくことで
保守性を上げることも、致し方ないかと思っています。

 

他にも

コメントによる、可読性のほかにも
「どこまでメソッドをきるか」とか「ネストの深さはどうだ」とか、色々とありますよね。

私個人的には、「リーダブルコード」の内容を根底に考えていけば
それなりに「読みやすいコード」が書けると思っています。

「リーダブルコード」を読んだことがないという方。
プログラマーなら、一読する価値は非常に高い書籍なので、ぜひ読んでみてくださいね!!


リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

 

まとめ

「コメントを残すか」に関して、個人的な思いをツラツラと書いてみましたが、

結局のところ、

プロジェクトとかチームのやり方に合わせる

しかない場合がほとんどだと思います。

個人で開発している方にとっては、自分で分かればよいので、自分の好きなようにやれば良いですし。

もし、コメントに対する運用方法が固まっていないようなプロジェクトの場合であれば、ぜひ参考にて頂ければと思います。

 

 

 
以上、
のらくら でした!!

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です