Pola Kompleksitas Visual yang Menurunkan Keterbacaan Kode (2023)

• Saat meninjau codebase baru-baru ini, muncul pengalaman merasa lelah secara mental meskipun kualitas kodenya baik
  • Hal ini berkaitan dengan keterbacaan, bukan kompleksitas kode itu sendiri
• Dihasilkan 8 pola untuk meningkatkan keterbacaan kode

Metrik keterbacaan kode dan metrik kompleksitas alternatif

• Tidak ada metrik yang universal dan digunakan secara luas untuk mengukur keterbacaan kode
• Yang ada hanya makalah akademik yang tidak dipakai di dunia nyata atau pendapat pribadi
• Alih-alih membuat metrik baru, fokus diberikan pada pola visual yang mudah didiskusikan siapa pun
• Syarat penting dalam metrik kompleksitas:
  • Harus bisa diterapkan pada cuplikan source code atau fungsi individual
  • Berfokus pada cara kode ditulis, bukan kompleksitas algoritme
  • Tidak berfokus pada elemen gaya (nama variabel, spasi, indentasi, dll.)

Metrik kompleksitas Halstead

• Metrik kompleksitas kode yang dikembangkan oleh Maurice Halstead pada 1970-an
• Dapat mengkuantifikasi cara penulisan kode tanpa bergantung pada bahasa atau platform
• Menghitung panjang, volume, dan tingkat kesulitan program berdasarkan jumlah operator dan operan
• Nilai pengukuran utama:
  • Jumlah operator unik (n1)
  • Jumlah operan unik (n2)
  • Jumlah total operator (N1)
  • Jumlah total operan (N2)
• Semakin banyak operator dan operan yang digunakan, semakin tinggi kompleksitas kode
• Karena definisi operator dan operan tidak selalu jelas di semua bahasa, penting untuk memakai alat yang konsisten

Insight dari kompleksitas Halstead

• Fungsi yang pendek dan memiliki sedikit variabel lebih mudah dibaca
• Minimalkan penggunaan operator atau syntactic sugar yang spesifik bahasa
• Penggunaan chain dalam functional programming (map/reduce/filter dan sejenisnya) akan menurunkan keterbacaan bila terlalu panjang

Kompleksitas kognitif (Cognitive Complexity)

• Metrik kompleksitas yang dikembangkan oleh SonarSource
• Upaya untuk mengukur kesulitan membaca kode dengan lebih akurat
• Tiga prinsip utama:
  1. Sintaks ringkas (shorthand constructs) mengurangi tingkat kesulitan membaca
  2. Putusnya alur nonlinier meningkatkan tingkat kesulitan
  3. Alur kontrol yang bertingkat meningkatkan tingkat kesulitan

Insight dari kompleksitas kognitif

• Sintaks ringkas itu padat, tetapi memiliki potensi risiko bug
• Pernyataan kondisi dan operator logika bila dipakai berlebihan akan menurunkan keterbacaan
• Penanganan exception adalah salah satu penyebab utama meningkatnya kompleksitas kode
• goto umumnya sebaiknya dihindari, tetapi dalam situasi tertentu bisa berguna
• Struktur kontrol bertingkat sebaiknya dikurangi sebisa mungkin

Bentuk, pola, dan variabel dalam fungsi

• "Bentuk" visual fungsi memainkan peran penting dalam keterbacaan kode
• Tiga prinsip untuk meningkatkan keterbacaan:
  1. Gunakan nama variabel yang jelas dan spesifik
  • Hindari duplikasi variabel (shadowing)
  • Gunakan nama yang mudah dibedakan secara visual (hindari nama mirip seperti i dan j)
  2. Perpendek masa hidup (liveness) variabel
  • Semakin pendek cakupan penggunaan variabel, semakin baik
  • Variabel yang bertahan lama melampaui batas fungsi meningkatkan kompleksitas
  3. Gunakan ulang pola kode yang sudah familier
  • Menjaga pola kode yang konsisten meningkatkan keterbacaan
  • Utamakan pola yang sudah dikenal daripada pendekatan baru

8 pola untuk meningkatkan keterbacaan kode

1. Kurangi jumlah baris/operator/operan – fungsi kecil dan sedikit variabel meningkatkan keterbacaan
2. Hindari pendekatan baru – pertahankan pola yang familier dalam codebase
3. Pengelompokan – pisahkan chain fungsi yang panjang, iterator, dan sejenisnya ke fungsi bantu
4. Sederhanakan kondisi – jaga pernyataan kondisi tetap pendek dan minimalkan campuran operator logika
5. Minimalkan goto – bila perlu, gunakan secara terbatas hanya untuk penanganan error
6. Minimalkan nesting – kurangi logika bertingkat, dan jika perlu pisahkan ke fungsi
7. Gunakan nama variabel yang jelas – pakai nama variabel yang spesifik dan tidak tumpang tindih
8. Perpendek masa hidup variabel – jaga tetap singkat di dalam fungsi dan jangan melampaui batas fungsi

Kesimpulan

• Keterbacaan kode adalah elemen penting dari kualitas kode
• Halstead dan Cognitive Complexity dapat membantu mengkuantifikasi masalah keterbacaan dan memberi arah perbaikan
• Menulis kode yang ringkas dan jelas membuat pemeliharaan lebih mudah serta mengurangi kemungkinan munculnya bug
• Penulisan kode yang optimal memprioritaskan kesederhanaan, konsistensi, dan kejelasan

[GN⁺]

Opini Hacker News

• Menghubungkan struktur pemrograman fungsional seperti map, reduce, dan filter memang ringkas, tetapi rantai yang panjang cenderung merusak keterbacaan

  • Itu bukan hal yang diisyaratkan oleh artikelnya
  • Ini terasa seperti keluhan umum yang menganggap sesuatu buruk hanya karena belum terbiasa
  • Setelah sedikit terbiasa, ini lebih mudah dibaca dan ditulis daripada cara lain
  • Penting untuk mempelajari dasar-dasar pemrograman fungsional
  • Tidak perlu menjelaskan Monad, tetapi setidaknya harus cukup akrab agar tidak asal menyalahkan map dan filter

• Aspek penting dari kode yang baik bersifat kualitatif dan literer

  • Ini bisa terasa tidak nyaman bagi programmer dan akademisi yang punya pola pikir matematis
  • Saya suka Dostoevsky dan Wodehouse, tetapi tulisan mereka sangat berbeda
  • Perlu waktu untuk memahami gaya sebuah codebase

• Masalah yang paling melelahkan saat membaca kode adalah kemutabelan

  • Kemampuan untuk "mengunci" variabel hanya sekali adalah anugerah besar
  • Proses memahami sebuah metode seharusnya meningkat secara monoton dari 0% ke 100%
  • Alasan GOTO berbahaya adalah karena sulit mengetahui keadaan variabel yang bisa berubah

• Fungsi kecil dan variabel yang sedikit pada umumnya lebih mudah dibaca

  • Fokus pada "keterbacaan" terlalu condong ke keterbacaan mikro
  • Ini membuat kode menjadi terlalu terpecah-pecah
  • Bahasa keluarga APL berada di kutub yang berlawanan

• TypeScript membuat kode lebih sulit dibaca

  • Tidak masalah jika model data tetap "atomik"
  • Jika bergantung pada inferensi tipe, sulit melacak field kembali ke lokasi asalnya

• Fungsi getOddness4 menimbulkan asimetri

  • Fungsi getOddness2 menawarkan pilihan yang simetris

• Artikelnya menarik, tetapi kurang memuaskan

  • Tidak setuju dengan pendapat untuk menghindari penggunaan operator atau syntax sugar yang spesifik bahasa
  • Struktur seperti map, reduce, dan filter, jika digunakan dengan baik, bisa menggantikan operator lain dan mengurangi "volume"

• Upaya untuk mendefinisikan keterbacaan patut diapresiasi

  • Bagi banyak orang, dimensi nyata keterbacaan bisa ditemukan lewat pengujian

• Kompleksitas kode dapat direpresentasikan oleh ukuran pohon sintaks

  • Pengurangan kompleksitas lokal tidak banyak memengaruhi kompleksitas keseluruhan

• Untuk rantai fungsi panjang atau callback, lebih baik membaginya ke dalam kelompok kecil dan menggunakan variabel dengan nama yang jelas

  • Kedua versi sama dalam hal efisiensi
  • Perbedaannya ada pada kompiler