「読ませる力」がエンジニアの価値を上げる

インプルの堀江です。

フルリモートで仕事をしており万年運動不足でして、最近になって筋肉は全てを解決するが真理なのではと思うようになってきました。そうだ、筋トレしよう。

“可読性”ってなんだ？
可読性が高いと何が良い？
「自分なら分かる」は、未来の自分すら裏切る
可読性が高いコードとは
あとがき

“可読性”ってなんだ？

「可読性（かどくせい）」という言葉を聞いたことがあるでしょうか？

辞書には、

文章や文字などが読みやすいこと。読みやすさ。とされています。

しかし実際は、もっと広い意味で使われることもあります。たとえば「コードの可読性が高い」と言ったら、それはそのプログラムの内容がスッと理解できるということ。

つまり「可読性が高い」とは、読む側の負担が少なく、すぐに理解できる状態を指します。

可読性が高いと何が良い？

結論から言うと、「読ませる力」があると、仕事が速く進む！です。

読みやすい文章やコードは、読んだ瞬間に内容が頭に入ってきます。理解するための“変換”や“考える”時間が不要になるからです。

たとえば、

チームの誰かが書いたコードがスッと理解できる
ドキュメントを読んだだけで仕様が分かる
昨日書いたコードを今日すぐに修正できる

こういう状態が「可読性が高い」ことによる恩恵です。

逆に、

変数名の意味が分からない
一文が長すぎて何を言ってるか分からない
インデントがぐちゃぐちゃで構造が追えない

そんな“可読性が低い”ものに出会うと、時間は奪われ、思考は濁り、ストレスも溜まります。

「自分なら分かる」は、未来の自分すら裏切る

可読性が低くなる原因のひとつが、「自分なら分かるから大丈夫」と思ってしまうこと。

でも、数週間後・数ヶ月後にそのコードや文章を読み返したとき、「え、これ何してたんだっけ…？」と自分の書いたものに戸惑う経験、ありませんか？

未来の自分を助けるためにも、「読ませる力」を意識して書くことは超重要です。

可読性が高いコードとは

では具体的に、コードの可読性を高めるにはどうすればいいのでしょうか？

重要かつ代表的な4つのポイントを、JavaScriptのコード例とあわせてご紹介します。

改行

適切に空行を入れるだけで、読む人の理解度はグッと上がります。

可読性が低い例：

function handleUserAction(user, settings) {
  if (user && user.isActive && settings && settings.enabled) { const permissions = getPermissions(user); if (permissions.includes('admin')) { const report = generateReport(user); sendReport(report); updateStatus(user, 'reported'); logAction(user, 'reportSent'); } else { alert('You do not have permission.'); } } else { console.error('Invalid user or settings.'); }
}

可読性が高い例：

function handleUserAction(user, settings) {
  if (user && user.isActive && settings && settings.enabled) {
    const permissions = getPermissions(user);

    if (permissions.includes('admin')) {
      const report = generateReport(user);
      sendReport(report);
      updateStatus(user, 'reported');
      logAction(user, 'reportSent');
    } else {
      alert('You do not have permission.');
    }

  } else {
    console.error('Invalid user or settings.');
  }
}

インデント

構造が一目でわかる。これは言うまでもないですね。

可読性が低い例：

function processUser(user){
if(user.isActive()){
if(user.hasPermission('edit')){
grantAccess(user);
logAccess(user);
sendNotification(user);
const report = generateReport(user.id);
storeReport(report);
updateUserStatus(user, 'processed');
}else{
console.log('No permission.');
}
}else{
console.log('User not active.');
}
}

可読性が高い例：

function processUser(user) {
  if (user.isActive()) {
    if (user.hasPermission('edit')) {
      grantAccess(user);
      logAccess(user);
      sendNotification(user);

      const report = generateReport(user.id);
      storeReport(report);

      updateUserStatus(user, 'processed');
    } else {
      console.log('No permission.');
    }
  } else {
    console.log('User not active.');
  }
}

命名

変数名・関数名等、任意の名前をつけられるものには意味を込めましょう。

可読性が低い例：

function p(u) {
  if (u.a && u.p === 'edit' && !u.b) {
    g(u);
    l(u);
    s(u);
    const r = gr(u.i);
    st(r);
    up(u, 'p');
  }
}

↑かなり頭が痛くなる例ですね

可読性が高い例：

function processUser(user) {
  if (
    user.isActive &&
    user.permission === 'edit' &&
    !user.isBanned
  ) {
    grantAccess(user);
    logAccess(user);
    sendNotification(user);

    const report = generateReport(user.id);
    storeReport(report);

    updateUserStatus(user, 'processed');
  }
}

コツは、「なぜこの処理をしているのか」が分かる文章を、最小限に書くことです。

可読性が低い例：

function processUser(user) {
  // 処理
  if (user.active) {
    if (user.permission === 'edit') {
      grantAccess(user); // アクセス
      logAccess(user); // ログ
      sendNotification(user); // 通知
      const report = generateReport(user.id); // レポート
      storeReport(report); // 保管
      updateUserStatus(user, 'processed'); // 更新
    }
  }
}

可読性が高い例：

function processUser(user) {
  // ユーザーがアクティブかつ編集権限を持ち、BANされていないことを確認
  if (user.active && user.permission === 'edit' && !user.banned) {
    // アクセス権を付与し、処理ログと通知を送る
    grantAccess(user);
    logAccess(user);
    sendNotification(user);

    // ユーザーに関するレポートを作成して保存する
    const report = generateReport(user.id);
    storeReport(report);

    // ユーザーの状態を「処理済み」に更新
    updateUserStatus(user, 'processed');
  }
}

コメントで可読性を高める方法の1つとして、TODOやNOTEといったアノテーションコメントを書くことが広く認知されており、とても役立ちます。

アノテーションコメントで可読性を高める例：

function calculateDiscount(price, user) {
  // TODO: ゴールド会員の特別割引ロジックを追加する
  // 現在は通常会員向けの処理のみ

  if (user.membership === 'regular') {
    return price * 0.9;
  }

  // NOTE: プレミアム会員は別の割引計算があるため、ここでは処理しない
  return price;
}

コードだけでは直接読み取れない、作成者だけが知っている情報をアノテーションコメントとして書くことで、

このコードは今どんな状態なのか
こういうコードにした意図は何なのか

を伝えることができます。

あとがき

エンジニアにとって「可読性」は、コードだけの話ではありません。

仕様書
コメント
チャット、メール
提案書

これらもすべて「読む人」がいます。そして、読みやすい＝伝わるです。つまり、読ませる力がある人は、どこでも通用します。

読ませる力はAIに正確な指示を出すためにも必要なので、これからのエンジニアにとっても必要な力と言えるでしょう。

もしこの記事を読んで「もっと読ませる力を磨きたい」「可読性を高める力を伸ばしたい」と思っていただけたなら、📘『リーダブル・コード ―より良いコードを書くためのシンプルで実践的なテクニック』を読むことをオススメします。

読ませる力を伸ばして、自分の価値を上げていきましょう！