ソースコードを読みやすくするためのアイデア

ソースコードを書いてますか？仕事で書いたり、個人開発で書いたり、ちょこっと試してみたり いろいろなシーンでソースコードを書くことがありますよね。

そのソースコードは１度きりではなく、必ず、同僚が見たり、上司やレビューワがチェックしたり、 自分自身で読み返すこともあります。 ソースコードは、大勢の人に何度も読まれ、そして修正されます。 そのため、読みやすいソースコードは理解を早くするだけでなく、修正のし易さも確保することができます。

この記事では、ソースコードを読みやすくするためのアイデアを説明します。

変数名に単位をつける

たとえば、remainTime（残り時間）という変数があったとします。

       var remainTime = 10;

このとき、remainTime は、１０分でしょうか？１０秒でしょうか？もしくは、１０ミリ秒でしょうか？ このソースコードだけでは、分かりませんよね。

そこで、変数名を remainTime_minutes（残り時間(分)）に変更してみます。

   var remainTime_minutes = 10;

このソースコードを見るだけで、１０分であると判断できます。コメントが無くても分かります。

数値型の変数名を決めるときには、単位をつけましょう。

ブール型の変数名は is や has をつける

ブール型とは、True・Falseどちらか一方のみ格納できる変数です。両方同時に格納できませんし、 これ以外の数値型や文字列型の値も格納できません。

   process_flag = true;

このようなソースコードがあったとき、どのような考えを持ちますか？ 「処理中」？「処理可能？」この変数名だけでは様々な可能性が考えられます。

   is_processing = true;

このようにisをつけておくと、be動詞＋～ing形で現在動作中であるという考えが容易になります。

また、

   coupon = true

よりも

   has_coupon = true

のように、has_～ という変数名にする方が、「このユーザーはクーポンを持っているのか」という 理解がしやすくなります。

ブール型の変数名を決めるときは、先頭に is や has をつけましょう。

誤解されにくい英単語を使用する

たとえば、getTotalScore() と computeTotalScore() という２つの関数名を考えます。

getScore()はどのような印象をもちますか？どこかデータベースやファイルに、「スコア合計」として 保存されている値を取得するだけの関数でしょうか？

一方、computeScore()はどうでしょう？各スコアそれぞれを合算して、スコア合計を求める関数でしょうか？

このように、処理の内容が想像できる関数名はソースコードの理解度が高まります。 それだけでなく、処理コストの想像もできるでしょう。数秒で終わる処理コストであれば問題になることは ありませんが、数分単位で処理コストがかかる場合は、パフォーマンスに影響するでしょう。

また、filter(age>=18) という関数であれば、この処理結果は１８才以上の人、でしょうか？

場合によっては、filter よりは select（抽出）やexclude（除外）の方がいいかもしれません。

※これは、読み手も書き手も英語スキルが影響してきます。英語ネイティブの人なら問題になりませんが、 日本語ネイティブな私は英語を勉強しないと、なかなか活用できません。 必要であれば、コーディング規約など、補助資料の活用を検討しましょう。

コードに現れないことをコメントで残す

ソースコードを読む上で最も重要なことは何でしょうか？私は、以下だと考えています。

  1. 処理コストなど、システム運用で懸念が発生すると思われる内容
  2. 改善の余地があると思われる内容、潜在バグ
  3. ビジネスロジック（業務知識や業務の流れ）
  4. データが一番最初に発生する箇所
  5. 外部システムや外部機関にアウトプットされるデータの内容

ソースコードから読み取れる内容はソースコードを読めばいいので、コメントを書く必要はありません。 ソースコードから読み取れない内容をコメントに書くべきです。

これらは別の設計書に書くべきと思われる方も多いかと思いますが、ソースコードにコメントとして書けば、 コードと内容をセットで残しておくことができます。 設計書に、index.js ファイル の connectDB()関数の 21行目 と記載しても、メンテナンスされるたびに 指し示すべき場所が変わります。その都度設計書を変更するのは面倒です。

コメントで残すべきは、コードとセットで説明したいがコードに現れない内容です。

関数から早く返す

以下の関数、どう思いますか？

function getMaxScore(){
    ...
    if (score == 100) return 100;
    ....
    reuturn calculatedScore;
}

return 文は必ずしも関数１つに１個まで、というルールはありません。 むしろ、早めに return を記載した方が、読み手はすぐに関数呼び出し元に戻れますので、 ソースコードを理解するスピードが格段に上がります。

return する内容が早めに決まるのであれば、早く return を記載してあげるべきです。 そうすることで、その関数がとてもシンプルに見えます。

コメント

タイトルとURLをコピーしました