Kata-kata "kode dokumentasi diri" adalah cara lain untuk mengatakan "kode yang dapat dibaca." Dengan sendirinya, itu tidak akan menggantikan dokumentasi ini atau komentar yang baik , tetapi dengan atau tanpa mereka itu pasti akan membuat hidup Anda dan kehidupan rekan Anda lebih mudah.

Mari kita lihat beberapa prinsip penting untuk membuat kode dokumentasi diri.

Jangan gunakan "angka ajaib"

Katakan padaku, apa maksud garis ini?

if (students.length > 23) { 

Cek apakah jumlah siswa di atas 23? Dan apa artinya itu? Mengapa tepatnya 23, dan bukan, katakanlah, 24?

Angka ajaib adalah angka tanpa konteks. Anda perlu meluangkan waktu dan upaya untuk memahami konteks ini. Singkirkan pekerjaan yang tidak perlu, segera berikan nomor penandaan:

 const maxClassSize = 23; if (students.length > maxClassSize) { 

Coba baca kodenya sekarang. Kami memeriksa bukan "apakah ada lebih banyak siswa dari 23", tetapi "apakah ada lebih banyak siswa daripada yang diakomodir kelas".

Gunakan nama yang jelas untuk variabel

Saya tidak tahu mengapa, tetapi sebelumnya saya selalu takut untuk membuat nama variabel panjang. Yang bodoh dari saya, karena rStuNms dan fStuNms mengerikan dibandingkan dengan r awStudentNames dan filteredStudentNames .

Apakah yang terakhir sepertinya masih panjang? Lalu pikirkan ini: setelah 2 minggu liburan dan bekerja dengan kode lain, Anda akan melupakan setengah dari singkatan. Yaitu, kemampuan membaca nama variabel saat bepergian adalah kemampuan membaca kode dengan cepat:

 const fStuNms = stus.map(s => sn) //    const filteredStudentNames = students.map(student => { return student.name; }); 

Tip bagus lainnya adalah menggunakan konvensi (konvensi penamaan). Jika variabelnya adalah Boolean, mulailah namanya dengan is atau has ( isEnrolled: true ). Jika variabel adalah array, gunakan jamak ( siswa ). Banyak angka harus dimulai dengan min atau maks . Dan nama fungsi harus mengandung kata kerja, misalnya, buatJadwal atau perbaruiNama nama . Berbicara tentang fitur ...

Tulis fungsi kecil bernama

Variabel bukan satu-satunya cara untuk membaca kode. Sebagai seorang programmer muda, saya menggunakan fungsi hanya untuk menghindari duplikasi kode . Pengungkapan nyata bagi saya adalah, pertama-tama, masuk akal untuk membuat fungsi untuk menggambarkan apa yang terjadi .

Luangkan beberapa detik untuk melihat kode ini dan katakan apa fungsinya:

 const handleSubmit = (event) => { event.preventDefault(); NoteAdapter.update(currentNote) .then(() => { setCurrentAlert('Saved!') setIsAlertVisible(true); setTimeout(() => setIsAlertVisible(false), 2000); }) .then(() => { if (hasTitleChanged) { context.setRefreshTitles(true); setHasTitleChanged(false); } }); }; 

Sekarang lakukan hal yang sama untuk kode:

 const showSaveAlertFor = (milliseconds) => () => { setCurrentAlert('Saved!') setIsAlertVisible(true); setTimeout( () => setIsAlertVisible(false), milliseconds, ); }; const updateTitleIfNew = () => { if (hasTitleChanged) { context.setRefreshTitles(true); setHasTitleChanged(false); } }; const handleSubmit = (event) => { event.preventDefault(); NoteAdapter.update(currentNote) .then(showSaveAlertFor(2000)) .then(updateTitleIfNew); }; 

Tampaknya ada lebih banyak karakter, tetapi seberapa jauh lebih mudah dibaca, bukan? Yang diperlukan hanyalah mendistribusikan operasi logis ke fungsi kecil bernama. Selain itu, fungsi kecil itu sendiri tidak perlu dibaca di sebagian besar situasi - ini adalah detail implementasi. Untuk memahami kode, lihat saja fungsi paling atas, yang terdiri dari rangkaian peristiwa yang mudah dipahami.

Namun lebih jauh - lebih lanjut, beberapa saat kemudian Anda akan menyadari bahwa fungsi sekecil itu sangat mudah digunakan kembali. Dapat digunakan kembali adalah konsekuensi dari peningkatan keterbacaan, dan bukan sebaliknya.

Tambahkan deskripsi tes yang berguna

Mungkin yang paling sedikit dibicarakan adalah tes yang didokumentasikan sendiri, tetapi sia-sia.

Katakanlah kita memiliki fungsi seperti ini:

 const getDailySchedule = (student, dayOfWeek) => { 

Bayangkan itu berisi banyak operasi berbeda: ia menerima jadwal selama sebulan; jika hari ini adalah hari libur, mengembalikan array kosong; jika siswa terdaftar di kelas tambahan, tambahkan mereka di akhir hari, dll. Secara umum, Anda memahami idenya: fungsinya kompleks dan alangkah baiknya menuliskan algoritme kerjanya di suatu tempat dengan kata-kata sederhana.

Mencoba memasukkannya ke dalam komentar adalah ide yang buruk: komentar akan menjadi usang dan bukan fakta bahwa itu akan diperbaiki pada waktunya. Apakah Anda tahu di mana rekaman algoritma operasi sesuai? Dalam tes:

 describe('getDailySchedule ', () => { it("   ", () => { it('  ,   ', () => { it('     ', () => { 

Ini adalah cara paling elegan untuk mengomentari kode tanpa komentar dalam kode.

Intinya: keterbacaan lebih penting daripada kepintaran

Siapa pun dapat menulis kode yang bisa dimengerti oleh dirinya sendiri, pengembang yang baik menulis kode yang bisa dimengerti orang lain . Jarang ada sesuatu yang penting dibuat oleh satu orang, yang berarti cepat atau lambat orang lain akan membaca kode Anda. Tetapi bahkan jika Anda yakin hanya Anda yang akan mempelajari beberapa kode, pertimbangkan bahwa Anda, hari ini dan Anda, dalam sebulan, adalah orang yang berbeda dalam hal kemampuan mengingat kode ini.