# コードリファクタリング手法:WordPress実務者向け6技法

URL: https://noonwp.com/ja/journal/code-refactoring-techniques-ja
Type: blog
Locale: ja
Published: 2026-06-29
Updated: 2026-07-04

---

> WordPress開発者向けの実践的なコードリファクタリング手法を6つ紹介。メソッド抽出、ガード節、DRY原則、FSEテンプレート整理などを現場の制約込みで解説する。

## コードリファクタリング手法:WordPress実務者向け6技法

コードリファクタリング手法の選び方ひとつで、WordPressのコードベースが1年後も保守できる状態を保つか、案件を引き継いだフリーランスが青ざめるfunctions.phpになるかが決まる。本稿ではブロックテーマ開発とプラグインPHPの現場で実際に効く、6つの技法を扱う。

![整理されたコード構造を示すノートPC画面のPHPコード](https://fdzlnqpwsaniezitwiuw.supabase.co/storage/v1/object/public/cms-media/noonwp/2026-06/54ffc6-inline1.webp)

## リファクタリングの合図となるコードの臭いとは

functions.phpが400行を超えたら、ひとつの明確な兆候だ。3か月前に「一時的に」複製されたブロックパターンが、クライアントのテーマディレクトリの中で微妙に異なる5つのバージョンとして存在しているのも同様だ。コードの臭いはバグではない。サイトは動いている。クライアントも満足している。しかし次にこのコードベースに触れる開発者は、本来40分で済むはずの作業を理解するために4時間を費やすことになる。

現場で使ってみると分かることがある。リファクタリングを先延ばしにするほど、そのコストは急激に上昇するという事実だ。2024年のStack Overflow調査では、開発者の62%が技術的負債を日々の最大のフラストレーションとして挙げている。WordPressの案件では、テンプレート関数の中に4階層もネストした条件分岐や、明確な所有者のないまま3つのファイルに散らばったregister_block_pattern()呼び出しという形でこれが表面化することが多い。

どの技法にも共通する前提条件がある。テストカバレッジだ。テストなきリファクタリングはリファクタリングではなく、楽観に基づく書き直しにすぎない。WordPressではWP-CLIとPHPUnitが最低限の基盤になる。PHPがほとんど存在しないFSE専用のブロックテーマでは、ローカルのLandoやLocalWP環境に対するPlaywrightのE2Eチェックが同じ役割を果たす。

## メソッド抽出:最初に手を伸ばす道具

WordPressのPHP開発でもっとも汎用性の高いリファクタリング技法がメソッド抽出だ。原則はシンプルで、ひとつの関数が複数のことをしているなら分割する。

プラグインのファイルアップロードハンドラを例にとる。元の実装はMIMEタイプの検証、ファイルサイズのチェック、S3 ACLの決定、添付ファイルのメタデータ書き込みを、すべて順番にこなす200行の関数だ。リファクタリング後は`is_valid_mime_type()`、`is_within_size_limit()`、`get_s3_acl()`、`write_attachment_meta()`という4つのメソッドに分かれる。外側の関数はほとんど注釈付きの文章のように読める。

Gutenbergのブロックテーマでも同じ原則が`functions.php`に当てはまる。ブロックスタイルの登録、エディタスクリプトのエンキュー、ブロックサポートの設定、カスタムクエリ変数の追加を、ひとつの`after_setup_theme`フックの中でまとめて行うテーマは、一度に多くをやりすぎている。これらを名前の付いた個別の関数に分割し、`/inc/`ディレクトリからインクルードする作業は、大げさな設計論ではない。1時間で把握できるコードベースと、案内なしには理解できないコードベースの違いを生む作業だ。

備考:この手法はWordPress 6.4以降で有効だ。ブロックフックAPIが追加した登録パターンは、分離しておくことで恩恵が大きい。

## ガード節がネストした条件分岐を解消する

本番環境で見てきたWordPressのPHPコードの中で、2番目に多い摩擦がネストした条件分岐だ。プラグイン開発でよく見るパターンはこうだ。関数がまず権限を確認し、次に投稿タイプが一致するか調べ、さらにメタ値を検証してから、ようやくロジックを実行する。それぞれのチェックが前のチェックの内側にネストされ、階段状のコードができあがる。

ガード節はこれを逆転させる。実行を妨げる各条件を、関数の先頭で早期リターンにする。成功した場合の処理は関数の末尾に置かれ、インデントもなく、波括弧の深さを追わずに読める。

`// Before: staircase of doom
function handle_submission( $post_id ) {
    if ( current_user_can( 'edit_posts' ) ) {
        if ( get_post_type( $post_id ) === 'project' ) {
            if ( get_post_meta( $post_id, '_status', true ) === 'pending' ) {
                // actual logic here
            }
        }
    }
}

// After: guard clauses
function handle_submission( $post_id ) {
    if ( ! current_user_can( 'edit_posts' ) ) return;
    if ( get_post_type( $post_id ) !== 'project' ) return;
    if ( get_post_meta( $post_id, '_status', true ) !== 'pending' ) return;

    // actual logic here
}`リファクタリング後のコードは短くなるだけでなく、それ以上に重要な点として、各条件を独立して読み、理解し、修正できるようになる。ビジネスロジックが変わったとき(必ず変わる)、その変更は的確に一箇所で済む。

![付箋ボードでモジュール構造のコード設計を検討する開発者](https://fdzlnqpwsaniezitwiuw.supabase.co/storage/v1/object/public/cms-media/noonwp/2026-06/406483-inline2.webp)

## ブロックパターンにおけるDRY原則:テンプレート重複をやめる

DRY(繰り返しを避ける)は、ブロックテーマ開発でもっとも頻繁に破られるリファクタリング原則だ。WordPressのフリーランスがクライアントサイトを構築するとき、初期のパターンライブラリは有機的に成長していくことが多い。ここにヒーローブロック、あそこにテスティモニアルセクション、という具合だ。開発3か月目には、80%が同一のマークアップを持つヒーローブロックのバリエーションが5つ存在し、それぞれサイトの異なるセクション向けにわずかにカスタマイズされている、というのがよくある状態だ。

ここでのリファクタリングのアプローチは、共通する構造を特定し、それを単一の正規パターンとして抽出し、見た目の違いはブロックパターンのバリエーションやグローバルスタイルで処理することだ。ツールの面でこれを後押しするのが[Create Block Themeプラグイン](https://wordpress.org/plugins/create-block-theme/)で、「開発中のテーマ」と「エクスポート可能で再利用できるテーマ」の間の境界を明確にしてくれる。

プラグインのPHPでは、同じ考え方は共通メソッドを親クラスに抽象化する形をとる。2つのアドオンクラスが同じオプションキーを読む`set_settings()`メソッドをそれぞれ定義しているなら、そのメソッドは共有の抽象クラスに置くべきだ。オプションキーが変わったときの修正は一箇所で済む。

この技法を見送るべき場合もある。重複しているパターンが、実際にはそれぞれ独立して進化していく編集上の文脈に仕えているケースだ。無理にDRYを適用すると、元の重複より悪い結合が生まれる。判断基準は、2つの重複が論理的に同じタイミングで変化するかどうかだ。イエスなら抽出する。ノーなら別々のままにしておく。

## FSEテンプレートのリファクタリング:モノリスからテンプレートパーツへ

Full Site Editingのテンプレートシステムは、多くのブロックテーマ開発者がまだ十分に活用できていない構造的なリファクタリングの機会をもたらした。ヘッダー全体のマークアップ、ナビゲーション、コンテンツエリア、サイドバー、フッターを1つのファイルに詰め込んだ`templates/single.html`は、FSEにおけるモノリシックな関数に相当する。動作はする。だが12種類の異なる投稿タイプを持つサイトで保守するのは不可能に近い。

リファクタリングの道筋はテンプレートパーツだ。ヘッダーを`parts/header.html`へ、フッターを`parts/footer.html`へ移し、それぞれ必要なテンプレートから`<!-- wp:template-part {"slug":"header"} /-->`で参照する。クライアントがナビゲーション構造を変更したとき、その変更は1つのファイルで完結し、あらゆる場所に伝播する。

これは机上の空論ではない。[WordPress公式ドキュメントのテンプレートパーツ解説](https://developer.wordpress.org/themes/templates/template-parts/)でも、ヘッダーやフッターを独立したパーツとして切り出す設計が推奨されており、同じパターンが公式レベルでも支持されていることがわかる。

テンプレートをいつリファクタリングすべきでないか、現場からの補足がある。10個のテンプレートがすべて微妙に異なり、クライアントが頻繁にサイトエディタで直接編集している場合、テンプレートパーツへの積極的な抽出はかえって混乱を招くことがある。サイトエディタのテンプレートパーツ用UIは改善されつつあるが、発見しやすさの面ではまだ摩擦が残る。技術に詳しくないクライアントには、アーキテクチャとしての洗練度が多少落ちても、可動部品が少ないほうが正しい判断であることが多い。

## 関数型PHPメソッドでループの煩雑さを減らす

PHPの組み込み配列関数(`array_map`、`array_filter`、`array_reduce`)は、WordPressのプラグインコードで十分に活用されていない。これらは明示的な`foreach`ループと中間変数を排除し、仕組みではなく意図を表現するコードを生み出す。

WordPressでよくあるパターンは、投稿オブジェクトの配列を反復して計算値を抽出し、ループの中でアキュムレータを組み立てるというものだ。関数型の等価物では、各投稿を変換するのに`array_map`を、最終値を計算するのに`array_reduce`を使う。結果は行数が減るだけでなく、それ以上に重要な点として、ループの中に可変状態が残らない。

この技法が適しているのは、その操作が本質的に変換や集約である場合だ。データベース書き込みやAPI呼び出しなど、項目ごとにエラー処理が必要な副作用を伴う操作には向かない。そうした場合は、明確なエラー境界を持つ明示的なループのほうが正しい選択だ。

![リファクタリング後に自動テスト結果を画面で確認する開発者](https://fdzlnqpwsaniezitwiuw.supabase.co/storage/v1/object/public/cms-media/noonwp/2026-06/5ef3dc-inline3.webp)

## theme.jsonをデザイントークンとして扱うリファクタリング

6つ目の技法はブロックテーマ開発に特有のもので、これまでとは異なる種類のリファクタリングにあたる。CSSとPHPにハードコードされた値を、名前付きのデザイントークンとして`theme.json`に移す作業だ。

`color: #1a1a2e`を6つの異なるCSSルールで定義していたり、同じフォントスタックを`style.css`とエディタ用スタイルシートの両方にハードコードしていたりするテーマには、保守上の問題がある。ブランドカラーが変わればハードコードされた値を探し回ることになり、フォントが変わればそれを2箇所以上で変更することになる。

`theme.json`はデザイン上の決定を明示的に、名前付きで扱うことでこれを解決する。カラーパレットの`"slug": "primary"`というエントリは、CSSの中では`var(--wp--preset--color--primary)`になる。`theme.json`の中の16進数値を変えれば、そのプリセットカラーを使うすべてのブロックが、フロントエンドでもサイトエディタでも自動的に更新される。

同じ原則はスペーシングのスケール、フォントサイズ、カスタムレイアウトの寸法にも当てはまる。`theme.json`のトークンを一貫して使うようにテーマをリファクタリングするのは、華やかな作業ではない。時間もかかる。ただ現場で見てきた限り、これを実施したサイトでは次のデザイン変更が明確に速くなり、エディタとフロントエンドの間のスタイルのずれも大きく減る。

## リファクタリングが逆効果になるとき

この記事の締めくくりとして言っておきたいのは、すべてのコードベースが積極的なリファクタリングの恩恵を受けるわけではないということだ。慎重になるべき3つの場面がある。

1つ目。納期まで2週間しかないクライアント案件だ。リファクタリングはリスクを持ち込む。機能を出荷し、負債を記録し、後片付けの予定を立てる。

2つ目。まだ十分に理解していないコードだ。リファクタリングにはそのコードが何をしているかについてのモデルが必要になる。そのモデルが不完全なら、リファクタリング後のバージョンは、一見付随的に見えて実は荷重を支えていた振る舞いを消してしまうかもしれない。

3つ目。半年以内に完全に置き換えられる予定のコードだ。McKinseyの2024年のデータでは、体系的なリファクタリングは場当たり的なアプローチと比べて40〜50%速く完了することが示されている。ただしその優位性は、リファクタリング後のコードが維持され続けることを前提にしている。コードが一時的なものなら、その投資は複利で効いてこない。

WordPressのコードベースをリファクタリングする前に自問すべきことがある。このコードが今何をしているか、一文で説明できるか。できないなら、書き直す前にまず読む番だ。

## FAQ

### WordPress開発におけるコードリファクタリングとは何か

既存のPHP関数やブロックパターン、FSEテンプレートを、動作を変えずに読みやすく保守しやすい構造へ組み替えることを指す。機能追加でもバグ修正でもない。目的はプロジェクトのライフサイクル全体を通じて保守しやすいクリーンな構造を得ることにある。

### ブロックテーマのfunctions.phpはリファクタリングすべきか

200〜300行を超えているなら、その通りだ。推奨されるのは、ブロックスタイルの登録、エディタスクリプト、ブロックサポート、カスタム投稿タイプといった単一の関心事ごとに、/inc/ディレクトリ内の専用ファイルへ分割し、functions.phpからインクルードする方法だ。結果として見通しやすく、テストしやすいコードになる。

### メソッド抽出というリファクタリング技法とは何か

複数のことを行う関数を、それぞれ1つのことだけを行う小さな名前付き関数へ分割することだ。WordPressのPHPでよくあるのは、入力検証、データ処理、データベース書き込みを行う大きなプラグイン関数を、3つの独立した名前付きメソッドに分割するケースだ。各メソッドは個別に読みやすく、テストしやすくなる。

### PHPにおけるガード節とは何か

実行を妨げる条件を処理するために、関数の先頭に置く早期リターン文のことだ。if-elseブロックの内側にロジックをネストする代わりに、条件を満たさない場合はすぐにreturnする。これによりWordPressのプラグインコードによくあるネストした階段状のパターンが解消され、成功時の実行経路が読みやすくなる。

### FSEテーマのリファクタリングにtheme.jsonがどう役立つか

theme.jsonを使えば、色、フォントサイズ、余白といったデザイントークンを名前付きで一度だけ定義できる。CSSやブロックのマークアップはCSSカスタムプロパティ経由でこのトークンを参照する。デザイン値を変更するときはtheme.jsonの1箇所を更新するだけで済み、古いWordPressテーマでよくある、複数のCSSファイルに散らばったハードコードされた16進数値の問題を解消できる。

### WordPressのコードをリファクタリングすべきでないのはどんなときか

慎重になるべき場面が3つある。納期が迫っておりリファクタリングがリスクを持ち込む場合、コードが何をしているかまだ明確に把握できていない場合(書き直す前にまず読む)、そして近いうちにコードが完全に置き換えられる場合だ。リファクタリングは投資であり、そのコードが今後も保守され続けて初めて回収できる。

### FSEのテンプレートパーツはコードリファクタリングとどう関係するか

Full Site Editingにおけるテンプレートパーツは、PHPにおけるメソッド抽出のFSE版にあたる。ヘッダー、フッター、コンテンツのマークアップをすべて含んだ1つの大きなテンプレートファイルの代わりに、繰り返し使われるセクションごとに名前付きテンプレートパーツとして抽出する。たとえばヘッダーを変更すれば、そのテンプレートパーツを参照するすべてのテンプレートに変更が伝播し、複数ファイルを手動で更新する必要がなくなる。