こんにちは、@codeship_techです。
皆さんコードを書くときにコメントってどれくらい書きますか？
ビッシリ書く人もいれば、ちょこちょこと補足で書く人、普段あまり書かないという人もいるかもしれません。
今回は普段あまりコメントを書かないという人にとって、コメントの書き方やメリットがわかる質問です。
プログラムのコメントって何を書いたらいいんですか？
色々用途はありますが、読み手の理解を助けるためにソースコードに情報を付加しましょう。
適切にコメントを使おう
みなさんは、ソースコードにコメントをちゃんと書いてますか？
コメントをうまく活用することで、効率よく開発や学習を進めることができます。
コメントを用いる目的には主要なものとして以下があります。
- 新しく覚えた内容をメモする
- ソースを整理して見やすくする
- 念のため残しておきたい実装を残しておく
- プログラムから読み取れない内容を補足する
新しく覚えた内容をメモする
プログラムを書いていて、わからないところや忘れていたところを調べてインプットしたとき、ソースコードにその要点などを残しておくと良いでしょう。
例えばJavaScriptのテンプレートリテラルの使い方を覚えたときとか。
コメントすること自体がアウトプットになって、習得度が増すことでしょう。
html
<body>
<div id="root"></div>
<script>
const greet = "Hello From JavaScript";
const list = ["melon", "lemon", "grape"];
// バッククオートで全体を囲い、${}で変数を囲う
document.getElementById("root").innerHTML = `
<h1>${greet} </h1>
<ul>
<li>${list[0]}</li>
<li>${list[1]}</li>
<li>${list[2]}</li>
</ul>
`;
</script>
</body>
合わせて読みたい：大量の文字列の結合方法
目標は「一年後に自分がソースを見て書いた意図を理解できるように」
ソースを整理して見やすくする
本格的なWebサイトなどを作ろうとすると、一枚のファイルのコード行数が膨大なものになったりします。
修正などしようと思ったときに見返すのも大変で、モチベーションが削がれたりします。
その時は、ソースコードを分類して、何がどこに書いてあるのかを整理するように説明書きを加えると良いでしょう。
例えば、CSSでヘッダーをスタイリングしている箇所や、記事部分のスタイリングをしている箇所を示す、といったように。
これだけで見違えるほど保守しやすいコードになります。
css
/*全体*/
*{
margin: 0;
padding : 0;
}
/*ヘッダー*/
....(ここにヘッダーのスタイリング)
/*本文：自己紹介*/
...
/*本文：ポートフォリオ紹介*/
...
/*フッター*/
....
念のため残しておきたい内容を実装しておく
もし、ある場所をコーディングするのに、当初Aという方法をとっていたとします。
しかし、Aと同じ処理で、Aより効率のよさそうなBという方法が見つかったので、Aの部分をBで置き換えたとします。
しかし後になってAの方が良いとわかったので、Bを消去してAを書き直すことに…
しかもAの書き方を忘れてしまったのでまた調べ直すことに…
こんな経験あると思います。
Aはまた使う可能性があるので、Bを一旦採用した後でもコメントとして残しておきましょう。
Aを調べ直す時間が勿体無いですよね。
コメントは「処理されない部分」です。
容量を圧迫することはありませんので、迷ったら残しておくこと。
プログラムから読み取れない内容を残しておく
「映画監督のコメンタリー」なんて言ったりします。
一見すると何をしているのか全くわからないようなコードを、補足説明するつもりで意図を書きましょう。
例えば、フィボナッチ数列の解を導くプログラムです。
どのような数式を再現しようとしたかなどをコメントで書いてあげると親切ですね。
Python
# フィボナッチ数列の解を分割統治によって求める
def fib(x):
# 初項a1 = 0, a2 = 1
if x <= 1:
return x
#第三項以降で、 an = a_n-1 + a_n_2
return fib(x-1) + fib(x-2)
読み手の立場になって考える
コメントをする最も本質的な目的は、「読み手の理解を助ける」ことです。
読み手とは、あなたではない他人かもしれませんし、ソースに何を書いたかを全く覚えていなくて修正をしようにも理解できず困っている1年後のあなたかもしれません(1年もたてば自分の記憶は他人のとなんら変わりません)。
今の自分で見て「？」と思うことは、はたから見て「？？？」と思うことです。
まずは自分の理解のために、コメントを残すところから始めましょう。
積極的にコメントして、良い開発ライフを送りたいものですね。
