プログラミングにおける「名前」「コメント」の付け方

今回はコードの全ての行に影響する、名前やコメントについてまとめてみた。

個々の変更は小さいけれど、それらを合わせれば、コードはもっと読みやすくなるはず！

明確な単語を選ぶ

その変数に「どんなデータが入っているか」を誰がみてもある程度、想像できる名前にする。

例えば、よく見かける「name」はあまり明確な単語ではない。

String name

この「name」では何の名前なのか前後の処理を確認しなければ理解できない。
ユーザの名前であれば「userName」だったり、ファイルの名前であれば「fileName」の方が明確になる。

もう一つの例は、「get」だ。これもまた、あまり明確な単語ではない。

GetPage(url)

この「Get」ではページをどこから取ってくるのか何も伝わらない。インターネットから取ってくるのであれば「FetchPage()」や「DownloadPage()」の方が明確になる。

英語はとてもバリエーション豊かな言語なので、状況に合わせて選ぶと良い。

誤解されない名前

以下はデータベースの問い合わせ結果を処理するコードである。

result = Database.filter("year <= 2020")

このresultには「year <= 2020のオブジェクト」「year <= 2020ではないオブジェクト」どちらが含まれているのだろうか。どちらかよくわからないのはfilterがあいまいな単語であるからだ。こういった単語は避けるべきである。
「選択する」のであればselect()、「除外する」のであればexclude()にした方がいい。

また、ブール値の変数やブール値を返す関数の名前を選ぶ際には、trueとfalseの意味を明確にする必要がある。
以下は危険な例である。

boolean readPassword = true

この「read」は2つの解釈の仕方がある。

・パスワードをこれから読み取る
・パスワードをすでに読み取っている

ここでは「read」の代わりに、needPasswordやuserIsAuthenticatedを使用するべき。
ブール値の変数名は、頭にis、has、can、shouldなどをつけたり、肯定形にしてわかりやすくする事が多い。

コメントすべきこと

自分の考え

// ここは〇〇の関係で、あえてこの書き方をしている

コメントから情報を得ることができるので、下手に最適化しようとして無駄に時間を使う必要がなくなる。

// このクラスは汚くなってきている
// サブクラス’〇〇’を作成して整理した方がいいかも

時間ができた時に修正しやすくなったり、誰かが見た時に修正してくれる可能性がある。

コードの欠陥

例えば、改善が必要な時には以下の書き方のように、問題を「見える状態」にしておく。

// TODO: もっと高速なアルゴリズムを使う
// TODO: JPEG以外のフォーマットにも対応させる

大切なのは、これからコードをどうしたいのかをコメントに記述すること。
そういうコメントを書くことで、コードの品質や状態を知らせたり、改善の方向を示したりできる。

コメントのルール

例えば、TODO: （大文字）は大きな問題に使って、小さな問題にはtodo: （小文字）を使うなど、
チーム開発を行う時にはコメントのルールを作っておくとやりやすい。

まとめ

変数や関数、クラスであっても名前は短いコメントだと思えばよく、いい名前をつけることで、多くの情報を伝えることができる。そして、コードは短くした方がいい。けれど、「理解するまでにかかる時間」を短くする方が大切！

kuga

IT/Webエンジニアとして勤務しています。

猫が大好きです。このところ毎日愛猫に枕を取られ続けています。