独学してるとつい軽視しがちなアレ

独学って覚えることがたくさんあって大変です。
相手にするプログラミング言語もたくさんありますし・・・
どのプログラミング言語をやったとしても無駄にならない内容ってありますか?

もちろん、あります。
たとえば、コメントを書くことですね。

え?
コメントってあのコメントですか?

はい。
そのコメントです。

でも、コメント書けてもプログラム動かないですよね?
それに、プログラミング言語ごとにコメントの書き方も違いますし・・・
どうして無駄にならないんですか?

コメントは軽視されがちですが、実は非常に重要なものなのです。
ここでいう有用なコメントというのは、プログラミング言語ごとのコメントの書き方(’で始めたり//で始めたりといったもの)ではありません。
コメントをきれいに書く行為自体のことなのです。

コメントをきれいにですか・・・
細かく書いていれば良いんじゃないんですかね?

細かく書きすぎてぐちゃぐちゃっとなっても読みづらいんじゃないでしょうか。

あー、確かにそうですね。
後で見返した時にこの行は何のために入れたんだっけと不思議に思うことがよくあります。
なので、コメントってあまり有益な情報にならないなぁと日々感じてました。

そのコメントをきれいにすると、もうコメント無しでは生きていけない体になりますよ。

いや・・・それはそれで困るんじゃないかと思いますけど・・・

ちょっと大げさすぎましたかね。
でも、本当に良いコメントに出会うと、ソースコードと同じように大切にしないといけないんだなと考えるようになります。
見えないところも美しく作るのがモチベーションアップにもつながりますし、いざバグった時に過去に書いた自分のコメントで助かることも多いのです。

なるほど。
でも、具体的にどのように書けばきれいになるのかイメージできないんですよね・・・

では、ここからは具体的に説明していきましょう。

プログラミング技法には色々なものがあります。
変数の頭文字は小文字にするとかクラスの頭文字は大文字にするとか、波括弧の位置は改行してからだとか、本当に色々。

これは、長い歴史の中でどうやったら可読性をあげられるか、ひいてはソースコード品質を確保できるかという観点から専門家の間で議論されて提唱されてきたものです。

なるほど・・・

コメントも似たような感じで、可読性を高めるために色々議論されてきました。
最近では、可読性だけではなく有効利用性も一緒に議論されています。

可読性という点では、下記のポイントを注意すれば格段に向上させることが可能であることがわかっています。
- 記号を水平線のように使って看板を記述する。
- 変数やメソッドの役割や目的を明記する。
- 引数や戻り値の取りうる値を明記する。

おー、なるほどぉ。
看板を記述するというのは盲点でした。
たしかに、ぱっと見でわかるようなデカデカとした看板があれば、読み物として読みやすそうですね。

はい。
看板は読み手の心をつかむという意味でも大切なのです。

続いて、有効利用性という点について説明しますね。
近年、JavaDocやDoxygenなど、ソースコードから詳細設計書を生成する便利なツールが出てきています。
アジャイル開発が増えてきているので、面倒なところは自動化しましょうっていう流れなのでしょうね。

なるほど。
アジャイルですか。

はい。
これらのツールは便利なのですが、何でもかんでも詳細設計書化できるかというとそうでもありません。
やっぱり、JavaDoc流やDoxygen流などの流派に則ったコメントの記載方法でないと認識してくれません。
しかし、これらの流派は世界共通の流派ですので、一度覚えてしまえば世界中どこででも使えます。

それは良いですね。
グローバルってテンション上がりますね。

JavaDoc流やDoxygen流はVS Codeなどの有名なエディタで補完プラグインがあったりしますので、まずはそういった補助ツールを使って覚えていくのが効率良いと思います。

いや~、まさかコメントがグローバルな話に広がっていくものだとは思っていませんでした。
面白かったです。

何か質問がありましたら、また来てください。

はい、ありがとうございました!
早速コメント見直してみます!
コメント