💡 Key Takeaways
- 1. Names Should Reveal Intent, Not Require Archaeology
- 2. Functions Should Do One Thing and Do It Well
- 3. Comments Should Explain Why, Not What
- 4. Keep Your Code DRY, But Not Bone Dry
Oleh Marcus Chen, Insinyur Perangkat Lunak Utama dengan 14 tahun membangun sistem yang dapat diskalakan di perusahaan Fortune 500 dan startup
💡 Poin Penting
- 1. Nama Harus Mengungkapkan Niat, Tidak Memerlukan Arkeologi
- 2. Fungsi Harus Melakukan Satu Hal dan Melakukannya dengan Baik
- 3. Komentar Harus Menjelaskan Mengapa, Tidak Apa
- 4. Jaga Kode Anda DRY, Tapi Tidak Terlalu Kering
Tiga tahun yang lalu, saya mewarisi sebuah kode yang membuat saya mempertanyakan pilihan karier saya. Tim sebelumnya sudah menyampaikan fitur dengan cepat—benar-benar cepat. Tetapi ketika saya membuka file layanan utama, saya menemukan 4.200 baris logika yang kusut, variabel yang dinamai temp2 dan finalFinal, dan fungsi yang melakukan tujuh belas hal berbeda. Sebuah perbaikan bug sederhana yang seharusnya memakan waktu satu jam menghabiskan waktu tiga hari. Proyek itu mengajarkan saya sesuatu yang penting: kecepatan tanpa disiplin menciptakan utang teknis yang terakumulasi seperti bunga kartu kredit pada 29% APR.
Sejak saat itu, saya menjadikan kode bersih sebagai obsesi saya. Saya telah merombak sistem warisan yang melayani 50 juta pengguna, membimbing lebih dari 80 pengembang, dan melihat tim-tim mengubah produktivitas mereka dengan mengadopsi prinsip-prinsip ini. Data ini sangat menggugah: tim yang menerapkan prinsip kode bersih mengurangi kepadatan bug sebesar 40-60% dan memotong waktu orientasi bagi pengembang baru hingga setengahnya. Yang lebih penting, mereka mengirimkan fitur lebih cepat dalam jangka panjang karena mereka tidak terus-menerus berjuang melawan basis kode mereka sendiri.
Kode bersih bukan tentang menjadi pedant atau mengikuti aturan hanya untuk kepentingannya sendiri. Ini tentang rasa hormat—rasa hormat untuk diri Anda di masa depan, rekan kerja Anda, dan pengembang berikutnya yang akan memelihara pekerjaan Anda pada pukul 2 pagi ketika produksi mati. Berikut adalah sepuluh prinsip yang mengubah cara saya menulis kode dan bagaimana tim-tim yang saya pimpin mengirimkan perangkat lunak.
1. Nama Harus Mengungkapkan Niat, Tidak Memerlukan Arkeologi
Pertama kali saya meninjau kode di perusahaan saya saat ini, saya menemui sebuah fungsi bernama processData(). Butuh waktu 45 menit bagi saya untuk memahami apa yang sebenarnya dilakukan: memvalidasi input pengguna, mengubah nilai mata uang, memperbarui tiga tabel basis data, mengirim dua email berbeda, dan mencatat peristiwa analitik. Nama tersebut tidak mengungkapkan apa-apa tentang kompleksitas ini.
Pemberian nama yang baik adalah dasar dari kode bersih karena kita membaca kode jauh lebih banyak daripada menulisnya. Studi menunjukkan bahwa pengembang menghabiskan 58% dari waktu mereka untuk membaca dan memahami kode dibandingkan dengan 42% yang benar-benar menulis atau memodifikasinya. Setiap nama yang tidak jelas adalah pajak pada waktu baca itu, yang dikalikan di seluruh pengembang yang menyentuh kode tersebut.
Berikut adalah kerangka pemberian nama saya: nama variabel atau fungsi harus menjawab tiga pertanyaan tanpa mengharuskan Anda membaca implementasinya. Apa yang diwakilinya? Apa yang dilakukannya? Mengapa ia ada? Variabel yang disebut d tidak menjawab salah satu dari ini. Variabel yang disebut daysSinceLastModification menjawab semua tiga pertanyaan.
Untuk fungsi, saya mengikuti pola kata kerja-nama dengan sangat disiplin. getUserById() jelas. get() tidak berguna. handleUserData() tidak jelas—mengelola bagaimana? Untuk variabel boolean, saya menggunakan predikat: isActive, hasPermission, canEdit. Ini terbaca secara alami dalam pernyataan kondisional: if (isActive && hasPermission) dibandingkan dengan if (active && permission).
Saya telah melihat tim menghabiskan ratusan jam karena seseorang mengabbreviate customer menjadi cust di separuh basis kode dan cstmr di separuh lainnya. Konsistensi sangat penting. Tetapkan konvensi penamaan lebih awal dan terapkan melalui tinjauan kode dan aturan linting. Diri Anda di masa depan akan berterima kasih kepada Anda ketika Anda sedang melakukan debugging pada tengah malam dan tidak perlu menguraikan apa yang diwakili tmp_val_2.
Satu teknik praktis yang saya gunakan: jika saya tidak dapat memikirkan nama yang baik segera, saya menulis komentar yang menggambarkan apa yang dilakukan variabel atau fungsi, lalu mengubah komentar itu menjadi nama. Jika nama menjadi terlalu panjang (lebih dari 4-5 kata), itu biasanya sinyal bahwa fungsi tersebut melakukan terlalu banyak dan perlu dibagi.
2. Fungsi Harus Melakukan Satu Hal dan Melakukannya Dengan Baik
Prinsip Tanggung Jawab Tunggal bukan hanya teori akademis—itu adalah perbedaan antara kode yang dapat dipelihara dan mimpi buruk pemeliharaan. Saya belajar ini dengan cara yang sulit ketika melakukan debugging pada fungsi sepanjang 300 baris yang menangani pendaftaran pengguna, verifikasi email, pemrosesan pembayaran, dan pelacakan analitik. Mencari bug itu memakan waktu enam jam. Memperbaikinya hanya memakan waktu lima menit.
"Rasio waktu yang dihabiskan untuk membaca dibandingkan dengan menulis kode jauh lebih dari 10 banding 1. Kami terus-menerus membaca kode lama sebagai bagian dari usaha untuk menulis kode baru. Membuatnya mudah dibaca akan membuatnya mudah untuk ditulis." — Robert C. Martin
Sebuah fungsi harus melakukan satu hal, melakukannya dengan baik, dan hanya melakukan hal itu. Tetapi apa yang dianggap sebagai "satu hal"? Aturan jari saya: jika Anda tidak dapat menggambarkan apa yang dilakukan fungsi dalam satu kalimat tanpa menggunakan kata "dan," berarti fungsi tersebut melakukan terlalu banyak. validateUserInput() melakukan satu hal. validateUserInputAndSaveToDatabase() melakukan dua hal dan harus dipisahkan.
Saya menargetkan fungsi yang memiliki panjang 10-20 baris. Beberapa pengembang berpikir ini ekstrem, tetapi fungsi yang kecil memiliki manfaat besar. Mereka lebih mudah untuk diuji—Anda dapat memverifikasi satu perilaku tanpa mengatur skenario yang kompleks. Mereka lebih mudah untuk digunakan kembali—fungsi yang kecil dan terfokus menjadi blok pembangun untuk operasi yang lebih besar. Mereka lebih mudah dipahami—Anda dapat memahami seluruh fungsi tanpa menggulir.
Ketika saya merombak fungsi besar, saya mencari jahitan alami di mana kode berubah tingkat abstraksi. Sebuah fungsi yang memvalidasi input, mengubah data, dan menyimpan ke basis data beroperasi pada tiga tingkat yang berbeda. Saya mengekstrak setiap tingkat menjadi fungsinya sendiri: validateOrderData(), transformOrderForStorage(), dan saveOrder(). Fungsi asli menjadi koordinator yang memanggil ketiga fungsi ini secara berurutan.
Pendekatan ini juga membuat penanganan kesalahan lebih bersih. Alih-alih blok try-catch bersarang yang mencakup 50 baris, setiap fungsi kecil menangani kesalahannya sendiri dengan tepat. Fungsi koordinator kemudian dapat menangani skenario kesalahan tingkat tinggi tanpa terjebak dalam rincian implementasi.
Saya telah mengukur dampak prinsip ini pada tim-tim saya. Setelah menerapkan batas ukuran fungsi yang ketat, waktu rata-rata kami untuk memperbaiki bug turun dari 4,2 jam menjadi 1,8 jam. Anggota tim baru menjadi produktif 40% lebih cepat karena mereka dapat memahami fungsi individual tanpa perlu memahami seluruh sistem terlebih dahulu.
3. Komentar Harus Menjelaskan Mengapa, Tidak Apa
Awalnya dalam karier saya, saya berpikir kode yang baik berarti banyak komentar. Saya akan menulis hal-hal seperti // tingkatkan penghitung sebesar 1 di atas counter++. Pengembang senior saya menarik saya ke samping dan berkata sesuatu yang mengubah perspektif saya: "Jika kode Anda memerlukan komentar untuk menjelaskan apa yang dilakukannya, kode Anda tidak cukup jelas."
| Aspek | Kode Kotor | Kode Bersih | Dampak |
|---|---|---|---|
| Nama Fungsi | processData(), doStuff(), handleIt() | validateAndTransformUserInput(), sendWelcomeEmail() | Mengurangi waktu pemahaman sebesar 70% |
| Panjang Fungsi | 200-500+ baris, beberapa tanggung jawab | 10-20 baris, tanggung jawab tunggal | Kepadatan bug berkurang 40-60% |
| Nama Variabel | temp2, finalFinal, x, data | userEmailAddress, validatedOrderTotal | Waktu orientasi berkurang setengah |
| Komentar | Menjelaskan apa yang dilakukan kode | Menjelaskan mengapa keputusan dibuat | Waktu pemeliharaan berkurang 50% |
| Duplikasi Kode | Logika yang sama disalin ke lebih dari 5 file | Diekstrak menjadi fungsi yang dapat digunakan kembali | Perubahan memerlukan 1 edit vs 5+ |
Komentar harus menjelaskan mengapa Anda membuat keputusan, bukan apa yang dilakukan kode. Kode itu sendiri harus dapat dijelaskan dengan baik melalui penamaan yang baik dan struktur yang jelas. Ketika saya melihat // loop melalui pengguna di atas loop for, itu adalah gangguan. Loop sudah menunjukkan bahwa itu melingkari pengguna. Tetapi komentar seperti // Menggunakan pencarian linier di sini karena array biasanya memiliki 5-10 item dan overhead pencarian biner tidak sebanding—itu berharga. Itu menjelaskan keputusan yang tidak jelas dari kode itu sendiri.
Saya menggunakan komentar untuk mendokumentasikan aturan bisnis yang tidak jelas, menjelaskan solusi untuk bug pustaka pihak ketiga, atau mengklarifikasi mengapa kami tidak menggunakan solusi "jelas". Misalnya: // Tidak dapat menggunakan async/await di sini karena Safari 12 tidak mendukungnya dalam pekerja layanan dan 8% pengguna kami masih menggunakan Safari 12. Komentar itu mencegah pengembang berikutnya dari "memperbaiki" sesuatu yang tidak rusak.
Komentar peringatan adalah kasus penggunaan sah lainnya. // PERINGATAN: Mengubah waktu tunggu ini mempengaruhi pembatasan laju dalam pemroses pembayaran. Lihat tiket #1234 sebelum memperbaiki. Ini mencegah pengembang yang berniat baik melakukan perubahan yang memiliki konsekuensi yang tidak terduga.