Panduan Lengkap: Kompleksitas Siklomatik di WordPress

Kompleksitas siklomatik mengukur jumlah jalur independen melalui sebuah fungsi, dan dalam callback render WordPress, angka ini naik lebih cepat dari ekspektasi sebagian besar developer. Sebuah callback render_block dengan tiga conditional, satu switch berdasarkan variasi block, dan satu loop mengiterasi block inner dapat mencapai nilai 12 atau 14 sebelum siapa pun menyadarinya. Itu tidak otomatis salah. Itu adalah angka yang perlu dibaca dengan benar sebelum memutuskan apakah akan refactor, deploy, atau mencari solusi lain.

Freelancer biasanya bertemu dengan metrik ini dalam dua cara: tidak pernah, karena tidak ada yang menjalankan tool di proyek klien kecil, atau salah, dengan mengimpor grosir dari panduan gaya Java enterprise di mana ceiling 10 diperlakukan sebagai dogma terlepas dari konteks. Kedua-duanya tidak melayani tema WordPress dengan baik. Artikel ini mencakup tiga kasus konkret: apa yang diukur angka ini dalam callback render Anda sendiri, mengapa pola generator AI cenderung mendorong lebih tinggi dari yang dilakukan manusia, dan cara membaca skor tanpa mengubah setiap fungsi menjadi maze helper satu baris.

Apa yang diukur kompleksitas siklomatik dalam callback render WordPress

Thomas McCabe mendefinisikan metrik ini pada 1976 sebagai jumlah jalur independen linier melalui graph kontrol aliran program. Dalam istilah sederhana: mulai dengan 1, tambahkan 1 untuk setiap if, elseif, case, for, foreach, while, catch, dan operator boolean (&&, ||) yang dapat membuat eksekusi bercabang. Callback render yang memeriksa is_admin(), melakukan loop melalui $attributes['items'], dan switch berdasarkan atribut layout sudah melewati 5 sebelum melakukan apa pun dengan data.

Dua hal membingungkan freelancer baru terhadap metrik ini. Pertama, itu mengukur branching, bukan panjang. Fungsi 200 baris tanpa conditional dapat memiliki skor 1. Fungsi 15 baris dengan lima ternary nested dapat memiliki skor 8. Kedua, itu tidak mengukur seberapa sulit kode dibaca, hanya berapa banyak path yang suite test perlukan untuk mencakup sepenuhnya. Fungsi dengan complexity 12 membutuhkan 12 kasus test berbeda untuk menjalankan setiap path. Sebagian besar pekerjaan klien WordPress dikirim dengan nol.

Poin terakhir adalah yang perlu direnungkan. Di retainer freelance tipikal, tidak ada yang menulis 12 kasus test untuk block hero homepage. Yang sebenarnya terjadi adalah klien mengklik tiga atau empat path yang secara pribadi mereka gunakan, menyebutnya selesai, dan delapan path lainnya tetap diuji sampai tiket support tiba enam bulan kemudian di path yang tidak ada orang yang latih. Kompleksitas siklomatik bukanlah preferensi gaya. Itu adalah proxy kasar untuk berapa banyak kode Anda yang telah benar-benar diverifikasi versus berapa banyak yang Anda percayakan pada keberuntungan.

Mengapa pola block yang dibuat AI cenderung skor lebih tinggi dalam metrik ini

Ini bagian yang sebagian besar penjelasan complexity lewatkan, karena ditulis untuk engineer backend, bukan untuk orang yang mengirim pola Gutenberg ke klien. Pola generator AI, termasuk Pattern Forge, cenderung menaikkan complexity dalam tiga cara spesifik dan dapat diprediksi.

Logika breakpoint responsif ditulis sebagai conditional nested daripada diektrak ke helper. Mirroring RTL menambahkan pengecekan direction ke hampir setiap keputusan layout, menggandakan branch count dalam tema bilingual. Dan block konten dinamis (post loops, query variations, conditional CTAs) menumpuk if chains di dalam callback render daripada mendelegasi ke fungsi lebih kecil, karena callback self-contained tunggal lebih mudah bagi model untuk generate dengan benar pada pass pertama.

Saya menjalankan Pattern Forge pada sebelas prompt di Juni 2026, dari kartu testimonial sederhana hingga post-grid penuh dengan filter, dan mengukur generated render callbacks dengan PHPMD. Median complexity: 9. Kartu testimonial menghasilkan 4. Grid post dengan filter, prompt dengan paling banyak conditional logic, mencapai 19. Itu bukan cacat spesifik Pattern Forge; output Elementor AI pada prompt filtered-grid setara menghasilkan 21 dalam pass yang sama. Keduanya sudah melewati titik di mana manusia harus membaca fungsi sekali sebelum mengirimnya ke situs klien.

Membaca skor: apa artinya 1 sampai 10, 11 sampai 20, dan 50+

Threshold di bawah ini bukan arbitrary. Mereka kembali ke rekomendasi NIST asli McCabe dan diulang oleh setiap vendor static analysis yang masih mengirim metrik hari ini.

• 1 sampai 10: straightforward, testable dalam jumlah kasus yang reasonable, risiko defect rendah.

• 11 sampai 20: moderate. Layak dibaca sekali lagi sebelum merge, terutama dalam kode yang developer klien berikutnya akan warisi.

• 21 sampai 50: complex. Menguji setiap path tidak praktis dengan tangan. Ini adalah tempat bug bersembunyi di branch yang tidak ada orang yang latih.

• 50 dan lebih: functionally untestable. Jika Anda menemukan ini dalam callback render, berhenti dan pisahkan sebelum menyentuh apa pun.

Marginalia: band ini menggambarkan risk, bukan aesthetics. Fungsi di 14 bukan "bad code." Ini adalah kode yang membutuhkan lebih banyak test coverage daripada yang paling proyek WordPress anggaran untuk.

Mengukurnya tanpa meninggalkan terminal

Anda tidak perlu dashboard SaaS berbayar untuk mendapatkan angka ini. Tiga tool mencakup hampir setiap setup freelance WordPress.

PHPMD mengirim aturan cyclomatic complexity dari box; arahkan pada direktori inc/ atau blocks/ tema dan itu flagging apa pun di atas threshold yang Anda set (10 adalah default sensible). PHPCS memiliki cakupan sama melalui sniff Generic.Metrics.CyclomaticComplexity, berguna jika proyek Anda sudah menjalankan PHPCS untuk WordPress Coding Standards dan Anda lebih memilih untuk tidak menambahkan second tool. churn-php mengambil angle berbeda: itu cross-references complexity terhadap git commit frequency, jadi itu surfaces class yang keduanya complex dan constantly touched, yang merupakan sharper signal untuk "refactor ini duluan" daripada complexity sendirian.

Tidak satupun ini memerlukan build step beyond Composer. Jalankan PHPMD dalam pre-commit hook, gagalkan commit melewati threshold Anda, dan masalah berhenti mencapai review klien sepenuhnya.

Untuk agency yang menjalankan beberapa tema klien sekaligus, ruleset PHPMD yang sama milik CI, bukan hanya locally. GitHub Actions step yang menjalankan phpmd blocks/,inc/ text phpmd-ruleset.xml pada setiap pull request biaya beberapa detik per build dan tangkap pola yang selalu slip melewati review solo: fungsi helper kecil yang dimulai di complexity 4, bertahan empat pull request "just one more condition", dan landing di 17 tanpa siapa pun memperhatikan slope. Commit history menunjukkan increment. Pull request diff tidak pernah menunjukkan total.

Posisi WordPress core terhadap static analysis di 2026

Core masih tertinggal. Proposal core team PHPStan memformalkan static analysis dalam workflow core, tetapi itu menargetkan type safety dan dead code, bukan complexity gate. Tidak ada trac ticket yang mengenkripsi complexity ceiling pada fungsi core, dan beberapa core render callbacks (render_block_core_query, misalnya) duduk well melewati 20 dengan measure apa pun. Core memprioritaskan backward compatibility atas refactor-for-score, yang merupakan trade-off defensible pada skala itu dan alasan buruk untuk copy-paste ke tema klien dengan tiga developer dan tidak ada regression suite.

Kasus bilingual: untangling callback render tema EN/AR

Salah satu klien saya menjalankan situs berita bilingual, Inggris dan Arab, dibangun di atas tema block dengan Polylang. Block featured-story homepage memiliki satu render callback menangani: switching post type, RTL layout mirroring, tiga card sizes, fallback untuk missing featured images, dan manual override untuk pinned stories. Complexity: 23.

Perbaikannya bukan rewrite. Saya mengextrak RTL mirroring ke fungsi sendirinya (get_card_direction_class()), pulled card-size logic ke dalam small match expression, dan left fallback dan pin-override logic di mana mereka, karena split lebih lanjut akan berarti passing lima parameter antara dua tiny functions untuk gain readability tidak. Final complexity: 11 untuk main callback, 3 untuk extracted helper. Empat belas menit pekerjaan, tested terhadap kombinasi locale yang sama sembilan Polylang pengiriman default.

Pelajarannya umum melewati klien satu ini. Support RTL hampir selalu complexity tax tersembunyi dalam proyek WordPress bilingual, karena itu jarang get designed dalam dari first commit. Ini tiba sebagai patch: pengecekan direction bolted ke conditional chain yang ada, lalu another, lalu ketiga untuk edge case di mana post tidak memiliki terjemahan Arab yet. Extract perhatian itu satu-satunya early, sebagai tiny function sendirinya dengan nama sendirinya, dan rest dari callback tetap legible bahkan ketika English-only feature list terus tumbuh di sekitarnya.

Kapan skor tinggi adalah fine, dan kapan merupakan signal untuk berhenti

Skip saran yang mengatakan setiap fungsi harus duduk di bawah 10 tidak peduli apa. Beberapa WordPress template PHP secara legitimate menjalankan lebih tinggi karena jumlah layout variations adalah actual requirement, bukan accident dari bad code. Komponen card yang theme.json-driven yang legally mendukung enam layouts, tiga sizes, dan dua directions memiliki real branching untuk account untuk. Chasing skor lebih rendah dengan extracting enam one-line helper functions, masing-masing dipanggil sekali, menggantikan satu readable function dengan maze indirection. Itu lebih buruk untuk developer berikutnya, bukan lebih baik.

Signal untuk actually berhenti dan refactor berbeda: complexity memanjat past 20 dalam fungsi yang tidak ada orang fully tested, complexity yang keeps naik setiap kali klien minta "satu variasi lebih", atau churn-php report menunjukkan class yang sama complex diedit dalam enam dari last ten commits Anda. Score sendirian bukan trigger. Score plus seberapa sering Anda takut menyentuh fungsi adalah.

Ada juga titik di mana refactoring PHP adalah wrong fix sepenuhnya. Jika checkout klien atau catalog logic telah spiral past apa yang WordPress hooks dirancang untuk carry cleanly, kadang-kadang honest answer bukan add_filter() call lain bersarang three conditionals dalam. Ini memberi tahu klien bahwa platform e-commerce dedicated akan carry logika itu lebih baik daripada WordPress plugin stack akan pernah.

Set folio: apa yang harus dicheck sebelum handoff berikutnya

Jalankan PHPMD terhadap blocks/ dan inc/ sebelum setiap client handoff, bukan hanya ketika sesuatu breaks. Flag apa pun di atas 15 untuk second read, dan apa pun di atas 20 untuk actual conversation tentang apakah requirement justify branching. Menurut panduan referensi SonarSource sendiri, fungsi melewati 10 sudah membutuhkan lebih banyak test cases daripada most teams menulis dengan tangan, yang merupakan real cost yang Anda manage, bukan angka sendirinya.

Tool yang generated pola, human atau AI, tidak bisa skip langkah ini. Baca callback render sekali sebelum Anda ship. Itu adalah seluruh praktik.