Geekly articles weekly

10 prinsip kode dokumentasi diri

Hai Hari ini saya ingin berbagi tips tentang penulisan kode yang sempurna dan dapat dimengerti, diambil dari buku Peter Goodlif, "The Craft of a Programmer // Praktek Menulis Kode yang Baik."

Tentu saja, akan menyenangkan untuk membaca buku yang menghibur ini kepada siapa saja yang menulis kode, tetapi bagi mereka yang sangat malas, tetapi yang ingin berhenti menyiksa kurang dan menyesatkan rekan-rekan mereka ( memiliki hati nurani ), saya menyajikan 10 prinsip kode dokumentasi diri di bawah kucing :

1. Tulis kode sederhana dengan format yang baik


Format presentasi memiliki dampak besar pada kemudahan memahami kode. Representasi yang masuk akal menyampaikan struktur kode: fungsi, loop, dan pernyataan bersyarat menjadi lebih jelas.

int fibonacci(int position) { if (position < 2) { return 1; } int previousButOne = 1; int previous = 1; int answer = 2; for (int n = 2; n < position; ++n) { previousButOne = previous; previous = answer; answer = previous + previousButOne; } return answer; }

  • Pastikan eksekusi normal kode Anda jelas. Penanganan kesalahan seharusnya tidak mengurangi urutan eksekusi normal. Konstruksi bersyarat if-then-else harus memiliki urutan cabang yang seragam (misalnya, selalu menempatkan cabang kode "reguler" sebelum cabang "penanganan kesalahan", atau sebaliknya).
  • Hindari banyak level pernyataan bersarang. Kalau tidak, kodenya menjadi rumit dan membutuhkan penjelasan yang luas. Secara umum diterima bahwa setiap fungsi seharusnya hanya memiliki satu titik keluar; ini dikenal sebagai kode Single Entry, Single Exit (SESE, satu input, satu output) . Tetapi biasanya pembatasan ini membuat sulit untuk membaca kode dan meningkatkan jumlah tingkat bersarang. Saya lebih suka opsi fungsi fibonacci di atas daripada opsi- gaya SESE berikut:

     int fibonacci(int position) { int answer = 1; if (position >= 2) { int previousButOne = 1; int previous = 1; for (int n = 2; n < position; ++n) { previousButOne = previous; previous = answer; answer = previous + previousButOne; } } return answer; }

    Saya akan menolak bersarang berlebihan demi pernyataan kembali tambahan - itu menjadi jauh lebih sulit untuk membaca fungsinya. Ketepatan menyembunyikan kembali di suatu tempat jauh di dalam fungsi sangat diragukan, tetapi perhitungan singkat yang sederhana pada awalnya membuat membaca sangat mudah.
  • Waspadalah terhadap optimasi kode yang menyebabkan kejelasan dalam algoritma yang mendasarinya. Optimalkan kode Anda hanya ketika menjadi jelas bahwa itu mengganggu kinerja program yang dapat diterima. Saat mengoptimalkan, buat komentar yang jelas mengenai fungsi bagian kode ini.

2. Pilih nama yang bermakna


Nama semua variabel, tipe, file, dan fungsi harus bermakna dan tidak menyesatkan. Nama harus menggambarkan dengan benar apa itu. Jika Anda tidak dapat menemukan nama yang bermakna, maka ada keraguan apakah Anda memahami operasi kode Anda.

Sistem penamaan harus konsisten dan tidak menimbulkan kejutan yang tidak menyenangkan. Pastikan variabel selalu digunakan hanya untuk tujuan yang namanya disarankan.

Pilihan nama yang baik mungkin merupakan cara terbaik untuk menghindari komentar yang tidak perlu. Nama adalah cara terbaik untuk membawa kode lebih dekat ke ekspresi bahasa alami.

3. Pecahkan kode menjadi fungsi independen


Bagaimana Anda memecah kode menjadi fungsi dan nama apa yang Anda berikan dapat membuat kode dimengerti atau benar-benar tidak bisa dipahami.

  • Satu fungsi, satu tindakan

Minimalkan efek samping yang tidak terduga, tidak peduli seberapa berguna efeknya. Mereka akan membutuhkan dokumentasi tambahan.
Tulis fungsi pendek. Mereka lebih mudah dimengerti. Anda dapat menavigasi dalam algoritme yang rumit jika dibagi menjadi beberapa bagian kecil dengan nama yang bermakna, tetapi ini tidak dapat dilakukan dalam kumpulan kode tanpa bentuk.

4. Pilih nama jenis yang bermakna


Sedapat mungkin, jelaskan batasan atau perilaku menggunakan fitur bahasa yang tersedia. Sebagai contoh:

  • Saat menentukan nilai yang tidak akan berubah, tetapkan tipe konstan untuk itu (gunakan const di C).
  • Jika variabel tidak boleh mengambil nilai negatif, gunakan tipe yang tidak ditandatangani (jika ada dalam bahasa).
  • Gunakan enumerasi untuk menggambarkan dataset terkait.
  • Pilih jenis variabel dengan benar. Dalam C / C ++, tulis ukuran ke variabel tipe size_t , dan hasil operasi aritmatika dengan pointer ke variabel tipe ptrdiff_t .

5. Gunakan konstanta bernama


Kode seperti if (counter == 76) membingungkan. Apa arti sihir dari 76? Apa arti dari cek ini? Praktek angka ajaib itu ganas. Mereka mengaburkan makna kode. Jauh lebih baik menulis seperti ini:

 const size_t bananas_per_cake = 76; ... if (count == bananas_per_cake) { //    }

Jika kode 76 konstan sering ditemukan dalam kode (permisi, bananas_per_cake ), keuntungan tambahan tercapai: ketika perlu mengubah isi pisang dalam pai, cukup untuk memodifikasi kode di satu tempat, daripada melakukan pencarian global / perubahan nomor 76, yang penuh dengan kesalahan.

Ini tidak hanya berlaku untuk angka, tetapi juga untuk string konstan. Lihatlah setiap literal dalam kode Anda, terutama jika itu terjadi berulang kali. Bukankah lebih baik menggunakan konstanta bernama bukan?

6. Sorot potongan kode penting


Coba sorot kode penting dengan latar belakang materi biasa. Di tempat yang tepat Anda harus mendapatkan perhatian pembaca. Ada sejumlah trik untuk ini. Sebagai contoh:

  • Tempatkan iklan di kelas dengan bijak. Pertama, informasi tentang objek terbuka harus pergi, karena itu adalah pengguna kelas yang membutuhkannya. Detail implementasi yang tertutup harus ditempatkan pada bagian akhir, karena kurang menarik bagi sebagian besar pembaca.
  • Jika memungkinkan, sembunyikan semua informasi yang tidak penting. Jangan meninggalkan sampah yang tidak perlu di ruang nama global. C ++ memiliki idiom pimpl, yang memungkinkan Anda untuk menyembunyikan detail implementasi kelas. (Meyers 97).
  • Jangan sembunyikan kode penting. Jangan menulis lebih dari satu pernyataan dalam satu baris dan buat pernyataan ini sederhana. Bahasa ini memungkinkan Anda untuk menulis operator for for loop yang sangat inventif, di mana semua logika sesuai dalam satu baris dengan bantuan banyak koma, tetapi operator tersebut sulit dibaca. Hindari mereka.
  • Batasi kedalaman bersarang pernyataan bersyarat. Kalau tidak, sulit untuk memperhatikan penanganan kasus yang sangat penting di balik tumpukan ifs dan tanda kurung.

7. Kombinasikan data terkait


Semua informasi terkait harus di satu tempat. Jika tidak, Anda akan membuat pembaca tidak hanya melompati lingkaran, tetapi juga mencari lingkaran ini dengan ESP. API untuk setiap komponen harus diwakili oleh satu file. Jika ada terlalu banyak informasi yang saling berhubungan untuk disajikan di satu tempat, ada baiknya merevisi arsitektur kode.

Jika memungkinkan, gabungkan objek menggunakan konstruksi bahasa. Di C ++ dan C #, Anda bisa menggabungkan elemen dalam namespace yang sama. Di Jawa, mekanisme bundling adalah mesin paket. Konstanta terkait dapat didefinisikan dalam enumerasi.

8. Memberi label file


Tempatkan blok komentar di awal file dengan deskripsi konten file dan proyek yang berkaitan. Ini tidak membutuhkan banyak pekerjaan, tetapi sangat bermanfaat. Siapa pun yang harus menemani file ini akan mendapatkan ide bagus tentang apa yang dihadapi. Judul ini mungkin memiliki arti khusus: sebagian besar perusahaan perangkat lunak, karena alasan hukum, mengharuskan setiap file sumber memiliki pernyataan hak cipta. Biasanya, header file terlihat seperti ini:

 /********************************************************* * File: Foo.java * Purpose: Foo class implementation * Notice: (c) 1066 Foo industries. All rights reserved. ********************************************************/

9. Tangani kesalahan dengan benar


Masukkan penanganan semua kesalahan dalam konteks yang paling cocok. Jika ada masalah membaca / menulis ke disk, itu harus diproses dalam kode yang berkaitan dengan akses ke disk. Untuk menangani kesalahan ini, Anda mungkin perlu membuat kesalahan lain (seperti pengecualian "Saya tidak dapat memuat file"), meneruskannya ke tingkat yang lebih tinggi. Ini berarti bahwa pada setiap level program, kesalahan harus merupakan deskripsi akurat dari masalah dalam konteksnya . Tidak masuk akal untuk menangani kesalahan yang terkait dengan kegagalan disk dalam kode antarmuka pengguna.

Kode yang didokumentasikan sendiri membantu pembaca memahami di mana kesalahan terjadi, apa artinya dan apa konsekuensinya bagi program saat ini.

10. Tulis komentar yang bermakna


Jadi, kami mencoba menghindari menulis komentar menggunakan metode pendokumentasian tidak langsung lainnya. Tetapi setelah Anda berusaha untuk menulis kode yang dapat dimengerti, segala sesuatu yang lain perlu diberikan komentar. Agar kode mudah dipahami, perlu ditambah dengan jumlah komentar yang sesuai . Yang mana

Coba trik lain dulu. Misalnya, periksa apakah Anda dapat membuat kode lebih jelas dengan mengubah nama atau dengan membuat fungsi pembantu, dan dengan demikian hindari berkomentar.


Saya yakin bahwa setelah diperkenalkannya beberapa prinsip ini ke dalam kebiasaan, Anda akan membuat satu programmer lebih bahagia. Dan Anda akan menjadi programmer yang bahagia ini. Kapan? Pada saat kembali bekerja pada kode-nya enam bulan lalu.

Source: https://habr.com/ru/post/id458264/

More articles:


All Articles