フロントエンジニアのリーダブルコード #3 コメントの書き方

「フロントエンジニアのリーダブルコード」の最後は、コメントの書き方です。この記事は、コードを書く開発者全員に役に立ちます。コメントは、多様性があり、言葉の捉え方は人それぞれなので、コードを書くより難しいです。

#3　コメントの書き方

「優れているコードを書くには、優れていないコードを書かないこと。」これがリーダブルコードの考えです。この記事でも、書くべきコメントより、書くべきではないコメントに注目したいと思います。

コードから抽出できることをコメントに書くべきではありません。学習目的ならば良いかもしれませんが、開発現場では必要ないでしょう。またコードを補正するようなコメントもやめましょう。

補正コメントを書く必要があるならば、そのコードを修正して下さい。例では、背景色を変更することをコメントで伝えていますが、関数名に(backgroundの)"bg"を付け加えるべきです。

定数にコメントをつける。名前が明確なのでコメントが必要ない定数もある。だけど、コメントをつけて改善できる定数は多いです。定数の値を決めた背景や、説明を記録することで一段と理解しやすいでしょう。

身内用のコメントだと思うかもしれないが、他の開発者はこのような背景が解りやすいコメントを求めています。

開発者はベストを尽くしているが、コードに欠陥が出てしまう場合がある。欠陥は、コメントに残しておくと良いだろう。参考書籍「リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック」には、以下のようにすると良いとされています。

チーム内で記法を決めます。コメントの先頭に記述をすることで、他の開発者がどこを修正すれば良いかすぐに判断出来ます。

次は、読み手の立場になって考えることです。他の開発者は、あなたのように熟知していません。しかし、無意識に、わかっていること前提のコメントを書いてしまいます。

※良い例ではありません。
上記のコードを見て、他の開発者は「あれ、要素をひとつひとつ処理するならmapでも良いのでは？」と思うかも知れません。しかし、このコードには背景があります。user_numの値を使って、外部の要素に何かしらの変化を加えているのです。コードが、他の処理と連動していることを知らずに、変更してしまうとトラブルの原因になってしまいます。トラブルを防ぐために、ハマりそうな罠をコメントに追記しておきましょう。

これまでのコメント書き方は、書籍「リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック」の第5章「コメントすべきことを知る」を参考にしました。第6章「コメントは正確で簡潔に」も開発現場ではとても役に立ちます。ぜひ拝見して見てください。参考コードはフロントエンジニア向けにしましたが、コメントは全ての開発者に役に立ちます。