PR

変数名や関数名を気分で省略するな|読みやすいコードの命名ルール

プログラムを書いていて「関数名が長くなりそうだし、ちょっと省略するか」って思うことはありますか?それ、安易にやると後で困るかもしれませんよ。

リファクタに時間が取られすぎて何を作ってるんだか分からなくならないように、最初から意識しておきましょう。

変数名や関数名の省略でコードが読みにくくなる理由 | 可読性が下がる

安易な省略はシンプルに読みづらくなります。例を交えて詳しく見ていきましょう。

よくある略語例とその問題点

title → ttl
count → cnt
index → idx

比較的よく見かけるものではありますが、パッと見で分かる確率は結構低いと思います。特にttlを見てtitleだと思いつける人はほぼいないのではないでしょうか。

コード内にこのような単語が大量にあるとそのコードが何をしているのか分かりにくくなります。断りなく使うのはやめた方がいいでしょう。

読みやすさを意識した命名の考え方

もしどうしても略語を使いたい場合は、以下のような基準で判断するのがおすすめです。

  • img(image)、txt(text)などWeb文脈で一般的な略語 → OK
  • ❌ 自作略語や一般的でない短縮形 → 誤読や混乱の原因

コード内に意味不明な略語が増えると、読む側が“翻訳作業”を強いられることになり、工数もミスも増加します。
読み手に優しい命名が結果として自分の作業効率も高めます。

自分の書いたコードはすぐに忘れてしまう

「自分が分かってるからいいの!」と思ったそこのあなた。自分が書いたコード、結構簡単に忘れます。コードの細かい部分や、特に「なぜそのようなコードになったか」の意図が抜け落ちやすいです。そうならないようにぜひ命名を工夫してほしいと思います。

命名は「意図を思い出せるヒント」になる

変数名や関数名は、上手に付けることで意図思い出すためのヒントになります。

命名には以下のような情報を含めると良いでしょう。

  • 処理の目的(何をするのか)
  • 対象やスコープ(どこに影響するのか)
  • 特殊な処理や例外的なロジックが含まれる場合は、そのヒント

JavaScriptの命名から学べること

ヒントという観点で考えると、JavaScriptの各種関数やメソッドの命名が参考になります。

document.getElementById
addEventListener
JSON.stringify

JavaScriptでは上記のような命名をされていますが、文章に近いものとなっています。確かに長いですが意図を汲み取りやすいし、誤読しにくくなっていますよね。

命名は未来の自分や他の開発者へのメッセージ。
省略よりも伝わりやすさを優先しましょう。

命名ルールはチーム内で統一すれば省略も可能?

とはいえ結局はチーム内もしくは自分の中で「この言葉は絶対にこういう意味だ」「この単語は常にこう省略する」とルール化されているなら正直なんでもいいです。重要なのはルール化されていて正しく運用されているか、です。

ルールが明確なら省略もアリ

たとえば、以下のようなルールが定着している場合は省略しても問題ないこともあります。

  • img → img要素のクラス名に限定する。
  • txt → テキストコンテンツを表す時にのみ使用する。
  • btn → ボタン用のクラス命名として使用する。

このように「この略語は常にこう使う」という共通認識があれば、読み手が迷うこともありません。

「やりすぎない」バランス感覚も大切

とはいえ、すべてを厳格に管理しようとするとかえって開発が窮屈になる場合もあります。

律儀にやるなら用語集や命名規則などをドキュメント化しておくことになるでしょうが、そこまでしなくてもとにかく共通理解が取れているなら良いかなと思います。

共通理解をベースに、必要以上に堅苦しくならないことです。

命名は未来の自分やチームへのメッセージ。省略より「伝わる命名」を選ぶことで、保守性・可読性が劇的に改善します。ぜひ意識してみてください。

よくある質問

Q
変数名を省略しても大丈夫ですか?
A

略語がチーム内で明確にルール化されている場合は問題ありません。ただし、自作略語や一般的でない省略は可読性や保守性を損なう原因になるため、できるだけ避けるのが無難です。

Q
命名を丁寧に行うことで、どんなメリットがありますか?
A

処理の意図や対象が明確になり、未来の自分やチームメンバーがコードを理解しやすくなります。その結果、保守・改修コストの削減や、チーム開発でのトラブル防止にもつながります。

この記事を書いた人
小林 秀樹

Web制作フリーランス9年目|ディレクター・フロントエンドエンジニア
「世界一初心者に優しい」→セカヤサ。

コーポレートサイトやLP、メディア立ち上げまで幅広く対応。コーディングを軸に、UX設計・SEOライティング・サイト運用まで一貫対応。

法律系オウンドメディア立ち上げ支援では、特定のキーワードでのSEO1位を実現し問い合わせ獲得に貢献。また大手専門学校サイトの大規模リニューアル(100ページ超)でのディレクションと実装の両面の経験あり。

最近では、AIツールによる自社サービスUI制作や、ChatGPTを活用した記事執筆フローの構築など、AI時代に対応した制作手法の実践にも注力している。

zenn:
https://zenn.dev/hideki_climax

制作実績:
https://tan-band-c66.notion.site/37abe7077b184b338fd8f53f6873ca1d

小林 秀樹をフォローする
プログラミングの考え方を学ぶ
スポンサーリンク
シェアする
小林 秀樹をフォローする

コメント

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