Sumur : sitepoint
Apakah menyenangkan menemukan dokumentasi diluar code dan tidak bermanfaat?
Ini adalah kesalahan yang rawan : Anda mengubah beberapa code, dan lupa untuk menghapus atau memperbarui dokumentasi. Memang dokumentasi yang buruk tidak akan merusak code, tapi bayangkan apa yang akan terjadi saat debugging. Anda membaca dokumentasi. Dokumentasi bilang A, tapi code bilang B. Bisa-bisa waktu kita terbuang hanya karena kepo kok akan hal ini, dan dalam kasus terburuk, bahkan bisa menyesatkan!
Tapi menulis code tanpa dokumentasi bukan merupakan pilihan. Dari 15 tahun pengalaman dalam dunia programing sang penulis yg saya kutip ini, ia belum pernah menemukan dokumentasi yang tidak berguna dalam sebuah code.
Namun, ada cara untuk mengurangi ketergantungan akan dokumentasi. Kita dapat menggunakan teknik coding tertentu untuk memperjelas code, gampangnya sih kita bisa menggunakan bahasa pemrogaman untuk keuntungan kita.
Hal ini tidak hanya membantu membuat code kita lebih mudah untuk dipahami, tetapi dapat juga membantu memperbaiki desain program secara keseluruhan!
Teknik conding jenis ini sering disebut juga dengan self documenting. Kita bisa menggunakan teknik ini dalam menulis code. Contoh yang diberikan di sini dalam JavaScript, kita dapat menerapkan sebagian besar teknik ini dalam bahasa lain juga.
Overview of Techniques
Beberapa programmer memasukkan dokumentasi sebagai self documenting dalam sebuah code. Pada artikel ini, kita hanya akan fokus pada code. Dokumentasi memang penting, tapi itu topik yang besar dan akan dibahas secara terpisah.
Kita dapat membagi teknik ini dalam tiga kategori:
- structural, di mana struktur code atau directories digunakan untuk memperjelas tujuan
- naming related, sejenis penamaan function atau variable
- syntax related, di mana kita menggunakan (atau menghindari penggunaan) fitur bahasa pemrogaman untuk memperjelas code.
Kelihatannya bukan hal yang sulit ya. Tantangannya adalah menentukan kapan dan teknik mana yang harus digunakan. Mari kita lihat beberapa contoh praktis seperti apa penggunaanya.
Structural
Pertama, mari kita lihat kategori struktural. perubahan struktural mengacu pada perubahan code untuk memperjalas kegunaannya.
Masukkan code dalam function
Ini sama dengan "extract function" refactoring - yang berarti bahwa kita mengambil code yang ada dan memindahkannya ke function baru: kita "extract" code keluar ke fungsi yang baru.
Sebagai contoh, bayangkan ouput dari line berikut:
var width = (value - 0.5) * 16;
Tidak begitu jelas; memberi dokumentasi bisa sangat membantu. Atau, kita bisa membuat function dan menjadikannya sebagai dokumentasi:
var width = emToPixels(value);
function emToPixels(ems) {
return (ems - 0.5) * 16;
}
Yang berubah adalah pemindahan perhitungan kedalam function. Nama function adalah deskripsi kegunaannya, jadi code tidak membutuhkan lagi komentar. Manfaat lainnya adalah, kita sekarang memiliki helper function yang bisa digunakan ditempat lain, jadi metode ini dapat membantu mengurangi duplikasi code.
Mengganti conditional expression dengan function
If dengan banyak operan bisa sulit untuk dipahami tanpa adanya dokumentasi. Kita bisa menggunakan metode diatas untuk memperjelasnya:
if(!el.offsetWidth || !el.offsetHeight) {
}
Apa tujuan dari kondisi di atas?
function isVisible(el) {
return el.offsetWidth && el.offsetHeight;
}
if(!isVisible(el)) {
}
Sekali lagi, kita pindahkan code ke dalam function dan code ini jauh lebih mudah untuk dipahami.
Mengganti expression dengan variable
Mengganti sesuatu dengan variable mirip-mirip sih seperti memindahkan code dalam bentuk function, tapi dari pada function, kita hanya menggunakan variable.
Mari kita lihat contoh dengan if lagi:
if(!el.offsetWidth || !el.offsetHeight) {
}
Alih-alih penggunaan function, kita juga bisa menjelaskannya dengan membentuk variabel:
var isVisible = el.offsetWidth && el.offsetHeight;
if(!isVisible) {
}
Ini bisa menjadi pilihan yang lebih baik dari pada penggunaan function - ambil contoh, ketika kita ingin menjelaskan logika yang spesifik untuk algoritma tertentu yang hanya digunakan di satu tempat saja.
Penggunaan umum untuk metode ini adalah perhitungan matematika:
return a * b + (c / d);
Kita bisa memperjelasnya dengan memisahkan perhitungan:
var multiplier = a * b;
var divisor = c / d;
return multiplier + divisor;
Bayangkan contoh di atas memiliki beberapa algoritma yang mudah dimengerti. Dalam kasus apapun, intinya kita bisa memindahkan complex expressions dalam variable yang bisa mempermudah untuk pemahaman code.
Class dan module interfaces
Interface - adalah, public methods dan properties - dari sebuah class atau module yang bisa bertindak sebagai dokumentasi atas cara penggunaannya.
Mari kita lihat contoh:
class Box {
setState(state) {
this.state = state;
}
getState() {
return this.state;
}
}
Class ini bisa memiliki beberapa code lain di dalamnya. Sengaja penulis ini memberikan kita contoh sederhana, untuk menggambarkan bagaimana public interface didokumentasikan.
Dapatkah pembaca memberitahu bagaimanakah penggunaan class ini? Mungkin dengan mencobanya..., ehm tetapi itu tidak begitu jelas.
Kedua function memiliki nama yang wajar: apa yang dilakukan adalah jelas dari namanya. Namun, tidak terlalu jelas bagaimana kita harus menggunakannya. Kemungkinan besar kita perlu membaca code yang lain atau dokumentasi class untuk mengetahuinya.
Bagaimana jika kita mengubahnya menjadi seperti ini:
class Box {
open() {
this.state = 'open';
}
close() {
this.state = 'closed';
}
isOpen() {
return this.state === 'open';
}
}
Jauh lebih mudah untuk mengetahui kegunaannya, iya kan?. Perhatikan kita hanya mengubah public interface, representasi internal masih sama dengan properti this.state.
Sekarang kita dapat mengetahui sekilas bagaimana class Box digunakan. Hal ini menunjukkan bahwa meskipun versi pertama memiliki penamaan function yang baik, paket lengkap tetap membingungkan, dan bagaimana, dengan sesuatu yang sederhana seperti ini, sesuatu bangetkan?. Yang sulit adalah kita harus memiliki pandangan yang luas.
Code grouping
Pengelompokan bagian berbeda dari code dapat juga berperan sebagai dokumentasi.
Misalnya, kita selalu ingin mendeklarasikan variabel sedekat mungki dimana mereka segera akan digunakan, dan mencoba untuk menggunakan kelompok variabel bersama-sama.
Ini dapat digunakan untuk menunjukkan hubungan antara bagian-bagian yang berbeda dari code, sehingga siapa pun yang merubahnya dikemudian hari tidak membutuhkan waktu yang lama untuk mengetahui bagian mana saja yang perlu diubah.
Perhatikan contoh berikut:
var foo = 1;
blah()
xyz();
bar(foo);
baz(1337);
quux(foo);
Sekilas bisa kita lihat berapa kali foo digunakan? Bandingkan dengan ini:
var foo = 1;
bar(foo);
quux(foo);
blah()
xyz();
baz(1337);
Dengan mengelompokkan penggunaan foo bersama-sama, kita dapat dengan mudah melihat bagian mana dari code yang berhubungan dengannya.
Use pure functions
Pure function jauh lebih mudah dimengerti daripada function yang bergantung pada state.
Apa itu pure function? Saat memanggil function dengan parameter yang sama, dan selalu menghasilkan output yang sama, kemungkinan besar bisa disebut "pure" function. Ini berarti function tidak harus memiliki efek atau bergantung pada state - seperti time, object properties, Ajax, dll.
Function ini mudah untuk dipahami, karena nilai-nilai yang memperngaruhi output dipassing secara explisit. Kita tidak perlu utak atik code sekitar untuk mencari tau asalnya bagaimana, atau apa yang mempengaruhi hasil, karena semuanya sudah jelas.
Alasan lainnya function jenis ini dibuat sebagai self-documenting code adalah kita bisa yakin akan hasil outputnya. Tidak peduli apa pun, function ini akan selalu menggembalikan output hanya berdasarkan parameter yang berikan. Hal ini juga tidak akan mempengaruhi eksternal, sehingga kita tidak perlu khawatir akan sesuatu yang tak terduga.
Contoh yang pas dalam hal ini adalah document.write(). Developer JS yang berpengalaman tahu tidak harus menggunakannya, tapi banyak pemula terjebak akan hal ini. Kadang bejalan dengan baik - dilain kesempatan tidak, dalam keadaan tertentu, dapat menghapus bersih seluruh halaman. Berbicara tentang efek samping!.
Directory dan file structure
Ketika penamaan file atau directory, ikuti kesepakatan penamaan yang sama dengan yang digunakan dalam project, ikuti standar dari bahasa pemrogaman yang dipilih.
Follow established naming conventions
Cobalah untuk mengikuti kesepakatan penamaan yang sama dalam code. Misalnya, jika Anda memiliki sebuah objek dari jenis tertentu, sebut saja nama yang sama:
var element = getElement();
Jangan tiba-tiba memutuskan untuk menyebutnya node:
var node = getElement();
Jika kita mengikuti kesepakatan yang sama seperti di tempat lain di codebase, siapa pun yang membaca dapat membuat asumsi aman tentang makna dari sesuatu berdasarkan apa artinya tempat lain.
Use meaningful errors
Undefined bukan sebuah object!
Mari coba untuk tidak mengikuti contoh JavaScript, dan mari kita pastikan kesalahan dalam code memiliki pesan yang bermakna di dalamnya.
Apa yang membuat pesan kesalahan bermakna?
- Itu harus menjelaskan apa masalahnya
- Jika mungkin, harus mencakup nilai variabel atau data lain yang menyebabkan kesalahan
- Key point: kesalahan harus membantu kita mencari tahu apa yang salah - oleh karenanya bertindak sebagai dokumentasi tentang bagaimana function seharusnya bekerja.
Syntax
Metode terkait syntax untuk code self-documenting bisa berupa sedikit bahasa yang spesifik. Misalnya, Ruby and Perl memungkinkan kita untuk melakukan segala macam trik sintaks aneh, which, in general, harus dihindari.
Mari kita lihat yang terjadi dengan JavaScript.
Don’t use syntax tricks
Jangan menggunakan trik aneh, ini bisa membingungkan:
imTricky && doMagic();
Setara dengan code ini, tampak jauh lebih manusiawi:
if(imTricky) {
doMagic();
}
Selalu gunakan bentuk terahir. Trik syntax tidak akan membantu siapa pun.
Use named constants, avoid magic values
Jika kita memiliki value kusus dalam code - seperti angka atau string - pertimbangkan penggunaan constant. Tampak lebih jelas dari pada sebelumnya, ketika melihat lagi coding setelah satu atau dua bulan lagi, tak akan ada yang mempertanyakan mengapa ada nomor tertentu dalam code.
const MEANING_OF_LIFE = 42;
(Jika tidak menggunakan ES6, bisa juga kita gunakan
var sama saja kok.)
Avoid boolean flags
Boolean flag dapat membuat kode sulit dipahami. Pertimbangkan hal ini:
myThing.setData({ x: 1 }, true);
Apakah nilainya true ? Kita sama sekali tidak tau, kecuali kita masuk ke dalam setData() dan mencari tahu.
Sebaliknya, kita menambahkan function lain, atau mengubah nama function yang ada:
myThing.mergeData({ x: 1 });
Sekarang kita dapat segera tahu apa yang terjadi.
Use language features to your advantage
Kita bahkan dapat menggunakan beberapa fitur dari bahasa pemrogaman yang dipilih untuk mencari tahu maksud di balik beberapa kode.
Sebuah contoh yang tepat di JavaScript adalah metode iterasi array:
var ids = [];
for(var i = 0; i < things.length; i++) {
ids.push(things[i].id);
}
Kode di atas mengumpulkan ID ke dalam array. Namun, untuk mengetahui itu, kita perlu membaca keseluruhan dari loop. Bandingkan dengan menggunakan map():
var ids = things.map(function(thing) {
return thing.id;
});
Dalam hal ini, kita langsung tahu bahwa ini menghasilkan array dari sesuatu, karena itulah tujuan dari map(). Ini bisa menguntungkan terutama jika kita memiliki logika perulangan yang lebih rumit. Berikut detail metod array iteration.
Contoh lain dengan JavaScript adalah key word const.
Seringkali, kita deklarasi variable yang nilainya seharusnya tidak berubah. Sebuah contoh yang sangat umum adalah ketika load modul dengan CommonJS:
var async = require('async');
Kita bisa membuat maksud tidak pernah berubah ini lebih jelas:
const async = require('async');
Sebagai manfaat tambahan, jika seseorang tidak sengaja merubahnya, kita akan mendapatkan error.
Anti-patterns
Dengan semua metode ini, kita bisa melakukan beberapa hal yang menakjubkan. Namun kita tetap harus waspada tentang...
Function singkat memang bagus dan mudah dimengerti, jika kita menggunakan function itu hanya disatu tempat, pertimbangkan untuk menggunakan metode "Mengganti expression dengan variable" sebagai gantinya.
Don’t force things
Seperti biasa, tidak ada cara yang benar-benar mutlak untuk melakukan hal ini. Oleh karena itu, jika sepertinya tidak cocok, jangan dipaksakan.
Conclusion
Membuat code kita self documenting salah satu cara untuk meningkatkan pemeliharaan code. Setiap dokumentasi adalah code tambahan yang tidak diinginkan yang harus dipelihara, sehingga meminimalkan dokumentasi adalah sasuatu yang baik.
Namun, code self documenting tidak menggantikan dokumentasi atau komentar. Misalnya, kode terbatas dalam mengekspresikan maksud, sehingga kita perlu memiliki dokumentasi yang baik juga. Dokumentasi API juga sangat penting untuk lib, seperti harus membaca code sungguh hal yang rumit kecuali lib kita sangat kecil.
