🧑‍🎓

Webエンジニアはそろそろ日本語変数名の利用を検討してもいいのでは？

2023/03/14に公開

自ブログからの引用です。

概要

言うまでもなくプログラミングを書く場合は英単語を利用するのが一般的であり、普段それについて疑いを持つことはほとんどないのではないかと思います。私自身、新規プロダクトの立ち上げで設計する際にも「日本語で書くか？」という議論した経験はありません。
しかしながら、DX(Digital Transformation)やDDD(Domain Driven Design)の潮流を考えると、多くの場面で単語の持つ細かなニュアンスへの重みが増してきていると感じます。
本記事では、日本語でプログラミングすることに関する周辺環境と個人的な見解をまとめます。

前提

想定読者 => 国内産業向けのサービス開発おいて日本人のエンジニアで構成された開発チーム
- 平均的なメンバーはTOEIC500~700点程度の所謂英語が読めるレベルのエンジニアで構成される
技術スタック => Webエンジニア
- 言語: TypeScript, HTML, CSS
- FW: React
- ドメイン駆動設計をベースとします

また、あくまで個人的な見解なので、意見が違う部分があれば冷静に読み飛ばして下さい。

何を日本語で書くべきか？

本記事で検討したいのは主に 変数名・関数名・クラス名 などを日本語に置き換えることに関してです。逆に以下の点は英語のままにした方が良いと考えています。

制御文

if, for などの制御文は日本語化する必要がありません。なぜなら、これらはTypeScript(プログラミング言語)というドメインの固有のユビキタス言語と捉えられるので、ifは他の何者でもなく(もしではなく)、if文なのです。なでしこなどプログラムのドメインすら日本語にするPJはありますが、それが読みやすいと感じるか否かは個人差があります。

システムドメインの単語 (専門用語)

プログラムより上の階層で、システムドメインの用語も日本語化する必要がありません。例えば、id => 識別子, トークン => 証拠など言い直す必要はなく、id, tokne自体がシステムのドメインで確立した専門用語です。

(圧倒的)メリット

議論のはじめとして、日本語変数名を利用するメリットに関してまとめて行きます。

認知コストの低下

認知コストは、認識に必要な時間や労力を指しますが、やや感覚的な面があり意外と難しい議論だと思います。

想定される反論としては以下が考えられます。

「英語でも問題を感じない」
「英語の方が本来の意味を捉えていてわかりやすい」

そこで、まずは認知コスト = 読解スピードとして検討してみたいと思います。
こちらのサイトによると、英語のネイティブスピーカーの平均が200～250WPMに対して、日本人の平均は80～100WPM前後と言われているそうです。
つまり、日本人が英語を読む速度はネイティブの1/2倍速がベースになります。(確かに、0.5倍速にするとリスニングもよく聞こえてくるという経験はあると思います)。この比をそのままネイティブと非ネイティブの差を考えると、日本人プログラマーにとって英語より日本語で記述されたプログラムの方が読解速度が2倍になるということになります。

また、英単語でつけられた変数名を読む時、みなさんは英単語の意味を暗黙に日本語に変換して理解していないでしょうか？例えば、IDやUserはそのまま理解できますが、Account Balanceという単語は口座残高と暗黙に変換して理解してないでしょうか？私たちの普段の生活にない概念なので、現実世界と紐づけるには一段変換の作業が必要になります。逆の見方をしてみると、日本人プログラマーは最初に日本語で思考してから、コードへの落とし込みを考えた段階で英単語に変換していくと思います。このように、英単語を利用するということは、日本語と英語で二重の知識が要求されることになり、認知負荷は倍増します。

念の為に補足しますが、英語が読める？読めない？ではなく、認知負荷がどうか？を焦点としています。個人の認知には当然ですが限界があり、うまく抑制することで本当に価値があることに注力し成果に繋げることができるという事実は多くのモダンな組織論に書かれています。

2.「英語の方が本来の意味を捉えていてわかりやすい」に関しては以下で検討します。

ドメイン駆動設計の良い実践

ドメイン駆動設計はドメインにフォーカスした設計手法であり、問題領域をどれだけ適切に過不足なくうまく言い得ていくか？(つまり上手にモデリングすること)というのが重要な要素となります。

ここで、一般的な話しですが言語は網目のようなもので、英語辞典には単語ごとに日本語訳が記載されていますが、多言語間で正確に一致する単語はあったりなかったりします。

そのため、問題領域が国内にあるシステムに関しては、日本語を使うことで最も正確にモデリングすることができると考えられます。近年では国内産業の関するバーティカルSaaSやDX系SaaSプロダクトをコアに開発している企業が増えてきており、多くの場面で日本語でコードに落とすことの価値が得られると考えいます。
もちろん、グローバル企業や英語圏のエンジニアが多く在籍する企業では英語でコーディングする方が認知コストの総和が最小化するために合理的と思います。

ドキュメンテーションの向上

日本語でプログラミングをしない理由を検索すると、

「エディタ上で変換がめんどくさい」
「記述量が増える」

などの理由が多く見られ、事実としてはその通りです。

ここで検討したいのが、そもそもエンジニアがプログラムを書く目的ってなんでしょうか？

エンジニアは時間軸に沿って適切なシステムを設計・構築・運用するロールです。成果物であるシステムはデジタル企業にとってVPを確立させるコアバリューになります。そして、「進化的アーキテクチャー」などに記載がある通り、ソフトウェアはソフトであることに価値があり、「DevOpsとLeanの科学」や「チームトポロジー」がいうように、システムそのものよりも高速な価値提供を実現するバリューストリームを維持する組織・チームに価値があります。
そういった潮流の中で、ドメイン駆動設計が注目を集めているのは、バリューストリームに参加する（ビジネスパートを含む）多くの関係者の力を借りながら、進化的(疎結合)なシステムをスムーズに構築していくのに上手く機能する手法であるからです。

そんなドメイン駆動設計のコアな概念として、ユビキタス言語があります。ユビキタス言語はドメインモデルに現れ、(ちょっと抽象的な概念ですが)境界づけられたコンテキストという重要な概念を構成します。そのため、DDDでは問題領域の分析から的確なユビキタス言語を蒸留することが前提的な作業になります。そして、この作業はエンジニアだけでなく、ドメインエキスパートやビジネスパートとの協業になり、ユビキタス言語は双方の認識を一致させるためのツールにもなります。コーディング作業は、こうして得られた概念(ユビキタス言語)に沿って、ドメインやロジックをプログラムに落とし込む作業でるため、(書きやすさより) 意味的な正しさや読みやすさが重要です。

また、別の視点でも考えてみたいと思います。ある意味プログラムコードは「機会が解釈可能なほど明確な仕様書」と捉えることができます。所謂、設計資料は多少の飛躍や誤字脱字があっても人間の脳ミソが上手く補完してくれますが、コードは1文字でも間違えるとうまく動作しません。
コードはそれほど詳細なドキュメントであるため、すぐに複雑性が増大しいわゆるスパゲッティと呼ばれるようなカオスなコードになります。そのため、数々のアーキテクチャーやコーディング原則、TypeScriptなどの(漸進的)型付言語などで構造化することで認知負荷の改善が図られます。このように仕様書の認知負荷を最小限に保つことに価値をおくのであれば、日本語で記述することも多くの日本人にとって効果的にな認知負荷の軽減方法になるのではないでしょうか。

例えば、新規のメンバーやプロダクトオーナーに対してソースコードを共有する場面で、相手は既存のコードをすぐに理解できるでしょうか？おそらく、ドメイン固有の知識が強く求められるプロダクトほど、英語そのままでは意味を捉えることが難しく、英語 => 日本語の変換ステップを踏まなくてなならないために余計な認知コストがかかり、有限な脳みそというリソースをむやみに消費してしまっている可能性があります。

直観で理解できる

多少英語が得意なエンジニアでも、日常的に英語を利用して生活している方はごくわずかなのではないでしょうか？プログラマーはエディターのUIや、フォントにこだわり認知負荷を軽減されている方も多くいると思いますが、そもそもの利用する言語に無頓着では「木を見て森をみず」な状態です。

コメントにWhatを書かなくなる

コードを書く時に、最小限で的確なコメントを残すことは可読性の意味で重要ですが、よく「Whatを書かずWhy(Why not)をかけ！」と言った議論があったります。では、なぜそもそもWhatを書いてしまうかというと、あくまで1つの理由として、周辺の説明変数や関数名などだけでコードの意図を的確に表現することができていないという点が挙げられます。つまり、一般的な日本人の英語力で複雑なロジックやドメイン知識をコードという厳密な仕様書に落としていく作業に一定のハードルがあります。その点、日本語で変数名をつけていればWhatを簡単かつ的確に表現することができるため、コメントは自然とWhyが多くなっていくと期待されます。

論より証拠

感覚の問題になりますが、実際に英語 => 日本語に書き直したコードの例を記載します。
テーマとしては不動産管理会社が、管理不動産の情報を入力して、DBに保存するコードです。
(コード生成と翻訳はchatgptにお願いしています。)

まずは普通の英単語を利用したコード

import mysql from 'mysql';

// MySQL接続情報
const connection = mysql.createConnection({
  host: 'localhost',
  user: 'root',
  password: 'password',
  database: 'your_database_name',
});

// 物件情報の型定義
interface Property {
  address: string;
  owner: string;
  type: string;
  price: number;
  area: number;
  layout: string;
  age: number;
  structure: string;
  rooms: number;
  bedrooms: number;
  bathrooms: number;
  parking: boolean;
  access: string;
  condition: string;
  rentalIncome: number;
  vacancy: boolean;
  documents: string;
}

// 物件情報をMySQLに格納する関数
function addProperty(property: Property): void {
  const sql = `
    INSERT INTO properties (address, owner, type, price, area, layout, age, structure, rooms, bedrooms, bathrooms, parking, access, condition, rental_income, vacancy, documents)
    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?);
  `;
  const values = [
    property.address,
    property.owner,
    property.type,
    property.price,
    property.area,
    property.layout,
    property.age,
    property.structure,
    property.rooms,
    property.bedrooms,
    property.bathrooms,
    property.parking,
    property.access,
    property.condition,
    property.rentalIncome,
    property.vacancy,
    property.documents,
  ];

  connection.query(sql, values, (error, results, fields) => {
    if (error) {
      console.error('Failed to add property to database:', error);
    } else {
      console.log('Property added to database:', results);
    }
  });
}

どうでしょう？ぱっと見であなたの脳みそに染み込んできましたか？
次は日本語を活用した場合です。

↓ 開く

import mysql from 'mysql';

// MySQL接続情報
const 接続情報 = mysql.createConnection({
  host: 'localhost',
  user: 'root',
  password: 'password',
  database: 'your_database_name',
});

// 物件情報の型定義
interface 物件情報 {
  住所: string;
  所有者: string;
  種別: string;
  価格: number;
  面積: number;
  間取り: string;
  築年数: number;
  構造: string;
  部屋数: number;
  ベッドルーム数: number;
  バスルーム数: number;
  駐車場有無: boolean;
  アクセス: string;
  状態: string;
  賃料収入: number;
  空室有無: boolean;
  書類: string;
}

// 物件情報をMySQLに格納する関数
function 物件情報を追加(物件情報: 物件情報): void {
  const sql = `
    INSERT INTO 物件情報 (住所, 所有者, 種別, 価格, 面積, 間取り, 築年数, 構造, 部屋数, ベッドルーム数, バスルーム数, 駐車場有無, アクセス, 状態, 賃料収入, 空室有無, 書類)
    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?);
  `;
  const values = [
    物件情報.住所,
    物件情報.所有者,
    物件情報.種別,
    物件情報.価格,
    物件情報.面積,
    物件情報.間取り,
    物件情報.築年数,
    物件情報.構造,
    物件情報.部屋数,
    物件情報.ベッドルーム数,
    物件情報.バスルーム数,
    物件情報.駐車場有無,
    物件情報.アクセス,
    物件情報.状態,
    物件情報.賃料収入,
    物件情報.空室有無,
    物件情報.書類,
  ];

  接続情報.query(sql, values, (error, results, fields) => {
    if (error) {
      console.error('物件情報のデータベースへの追加に失敗しました:', error);
    } else {
      console.log('物件情報をデータベースに追加しました:', results);
    }
  });

</details>

実際に利用可能か？

利用可能: ✅, 利用不可: ❌

JS (✅)
- ECMAScript source text is a sequence of Unicode code points.
HTML (❌)
- 開始タグの最初の文字は、U+003C LESS-THAN SIGN 文字 < でなければならない。
CSS (✅)
- https://stackoverflow.com/questions/19123336/can-i-safely-use-unicode-characters-e-g-accents-in-css-class-names-or-ids#:~:text=from the css specification
WebComponent (?)
- まだ明確に定まっていない？
React (✅)
- 最終的にJSに変換される
- コンポーネント名は残らない
MySQL (✅)
- 参考
DynamoDB (▲)
- テーブル名、Index名だけ下記のルールに従う
- 名前付けルール
Github (✅)
- git config --global core.quotePath false で利用可能
- 参考
OS (✅)
- (今時マルチバイトのファイル名が使えないOSがあるのか？)

このように多くの環境では問題なく利用できるようです。
HTMLそのものには日本語タグ名を利用することはできませんが、Reactを介しての利用は可能です。
DynamoDBなど、どうしてもalphanumericな文字列が要求される環境もありますので、腐敗防止層などで吸収する必要がありそうです。

想定される意見

打ちづらい
- その通りだと思います。ただ、コードは書きやすさより、読みやすさが重要という認識をすり合わせることができれば運用は可能だと思います。
外国人エンジニアとのコラボレーションがしづらい
- コラボレーションするメンバーを含めチーム全体で、認知負荷を最小限に止めるに方針を決めると良いと思います。
- 現状日本人のみでチーム組成されている場合は、将来的に外国人エンジニアと協業する可能性がどのくらいあるでしょうか？また、現状の英語はネイティブが読める英語になっているでしょうか？(ローマ字とかは論外ですが。)
プロダクションコードが汚れる
- フロントエンドに関してはバンドル + Minify(Uglify)が基本なので、本番コードが汚染される心配はないと思われます。
なんかバグるんじゃ？
- 利用技術の下調べは前提になりそうですね、、
英語力がおちる
- 業務時間では価値のあるコードを生み出すことに注力するべきです。ただ、エンジニアに英語力が要求される場面は海外の書籍・ブログ記事を読んだり、フレームワークなどのドキュメントやその他一次情報を参照する時が多いと思うので特段問題はないと思います。
英語を勉強するべき
- 自分がテックリードだったとしてチーム英語力が完成するのはいつになるでしょうか？それまでのコードの品質はどう担保するのでしょうか？そして、チームは成果をいつまでに出す必要があるでしょうか？
なんかきもい
- めっちゃ分かりますw当たり前を疑うような話なので、気持ち悪さはどうしてもあります。コードの価値を焦点にフラットに方針を検討できればと思います。

提案

チームメンバーの読解速度を確認してみる

前提になるのはチームの英語力になります。そこで、チームで読解スピードを計測してみるのはいかがでしょうか？
こちら https://www.sokunousokudoku.net/measuresan/ のようなサイトで2, 3数分程度で実施することができます。
ただし、エンジニアは英語ができないといけないという暗黙のバイアスは強く感じるところなので、心理的安全性を保ち正直に実施と結果の申告してもらえるような風土作りは案外難しいかもしれません。

漸進的に導入する

既存のプロダクトにいきなり日本語を混ぜていくのは非常に抵抗を感じる部分があると思います。そこで、セグメントを切りながら日本語を漸進的に導入していくのはどうでしょうか？
最初はドメイン知識が凝縮しているドメインモデル周辺から日本語を導入していくことで、先述のメリットを効率よく実現でき、ドメイン知識をよりわかりやすく緻密に表現することができる様になります。ドメインモデルでの日本語活用に成功したら、次はDomainServiceやApplicationServiceに実装するUseCaseなどを日本語にすると良いと思います。その後は、コンポーネント名、DAO、DTOなどセグメントを切って実践していくのが良いと思います。

まずはプライベートプロダクトで試す

個人的な話ですが、多肉植物の栽培にはまっており、灌水や植え替えを管理するWebアプリケーションをReact + Firebaseで開発しているのですが、ここで日本語変数名を利用しています。これまでも、いくつかプライベートプロダクトを開発してきましたが、日本語でプログラムされていることで少し時間が開いても読み直しが圧倒的に楽であることを実感しています。また、灌水、科・属・種、施肥、耐寒性と行った園芸特有の用語をいちいち英語で考えるよりも何も考えずにコードに起こすことができます。FireStoreでも日本語のコレクション名を利用していますが、今のところ問題は出ていません。唯一の欠点は、やはり変換が終わらないとエディタのサジェストが利用できないので、書き心地の点はアルファベットを利用した方が良いです。ただ、メリットの方が上回ることを実感しています。

まとめ

個人的な見解をまとめた記事なので、読んで不快感を感じた方も多くいると察しますが、当たり前のことでも日々疑いながら改善のサイクルを回していくことでエンジニアとしてのアウトプットをより高めていきたいと考えています。
私自身も現在働いている会社でのPJでは普通に英語でコーディングしています。しかし、国内向けのSaaSプロダクトのため専門用語の取り扱いには日頃から課題を感じていました。
過去日本語でコーディングすることが明らかにアンチパターンだった時代がありますが、時代は繰り替えします。
例えば、Javaの厳しい型制約への課題から動的言語が流行りましたが、プロダクトが大規模になるに連れて再びTSやGOなどのように人間のために型を利用できる言語が再び注目されました。
日本語プログラミングに関しても環境が整えば再考されるタイミングが出てくるのではないかと思っています。

まとめると私が考える、日本語でプログラムを書くメリットは以下の通りです。

認知コストが下がる

コードのドキュメントとしての価値が上がる

ドメイン駆動設計をより上手く実践できる

複雑なロジックやドメイン知識のコードへの落とし込み作業が楽になる

末筆ながら、長い記事を読んでいただいた方はありがとうございましたmm

参考

漢字の様なマルチバイト文字 ... 避けた方が良い出でしょう。
DBMSの選択肢が増えた現在、DBMSの移植性を低下させるコーディング要素は極力避けるべきです。

達人に学ぶSQL徹底指南書

GitHubで編集を提案