Dokumentasi dengan Komentar
Diperkenalkan| English | Makna |
|---|---|
| comment/ˈkɒment/ | komentar |
Komentar tidak memperbaiki rumus yang aktif
- Untuk harga 100,
total = price * 10 / 100;menghitung 10 meskipun ada komentar yang berbunyi "jumlah dibayar setelah diskon sepuluh persen". Mengedit penjelasan tersebut tidak membuat ekspresi menghitung 90. - Ubah ekspresi aktif menjadi
price * 90 / 100untuk menghitung pembayaran yang dimaksud dalam contoh bilangan bulat ini. Komentar dapat mengungkap kebijakan yang dimaksud; verifikasi bahwa kode mengimplementasikannya.
Identifikasi teks yang dikecualikan dari kode
//memulai komentar hingga baris baru./*memulai komentar blok hingga*/berikutnya; komentar blok tidak bersarang. Delimiter di dalam literal string adalah teks, sehingga"https://example.com"tidak memulai komentar.- Teks komentar tidak dieksekusi sebagai pernyataan Java. Menambahkan penjelasan terpisah meninggalkan ekspresi aktif tetap sama; menempatkan
//sebelum penugasan aktif menghilangkan penugasan tersebut dari kode yang dikompilasi dan dapat mengubah perilaku.
Letakkan tag Javadoc pada baris terpisah
- Komentar dokumentasi
/** ... */segera sebelum deklaratasi dapat diproses oleh Javadoc. Ringkasannya menjelaskan operasi; tag blok seperti@paramdan@returnmemulai baris sendiri setelah spasi opsional dan*. - Kelas lengkap di bawah ini mendokumentasikan jari-jari non-negatif dan mengembalikan luas lingkarannya. Tag-tag tersebut menggambarkan input, output, dan input yang ditolak; komentar saja tidak membatasi pra-kondisi, sehingga metode secara eksplisit memeriksa jari-jari negatif.
/** Circle-area calculations for finite radii. */
public class AreaDoc {
/**
* Returns the area of a circle for a finite radius.
* @param r the non-negative radius
* @return the area in squared radius units
* @throws IllegalArgumentException if r is negative
*/
public static double area(double r) {
if (r < 0) {
throw new IllegalArgumentException("Negative radius");
}
return Math.PI * r * r;
}
}
Javadoc mengenali @param sebagai tag blok ketika disisipkan setelah teks ringkasan pada baris yang sama.
Difficulty 1/5 · 100 coins + a small bonus on first completion today
Tag blok dimulai pada baris sendiri setelah spasi opsional dan bintang awal opsional. Gunakan komentar multi-baris yang ditunjukkan.
Jelaskan keputusan yang tidak terlihat pembaca
- Komentar diskon yang berguna mungkin menyatakan "pembayaran adalah 90% dari harga tertera; latihan ini menggunakan harga bilangan bulat". Ini menjelaskan kebijakan dan asumsi, sementara
// multiply by 90hanyalah pengulangan operasi. - Ringkasan metode publik berguna bahkan ketika isinya pendek: pemanggil memerlukan kontraknya tanpa mempelajari implementasinya. Pilihlah penjelasan yang menyediakan konteks yang hilang daripada menyatakan setiap komentar deskriptif berlebihan.
Ketika program Java berjalan, komentar adalah...
Difficulty 1/5 · 100 coins + a small bonus on first completion today
Komentar untuk manusia — Java mengabaikannya.
Yang mana memulai komentar satu-baris dalam Java?
Difficulty 1/5 · 100 coins + a small bonus on first completion today
// berjalan hingga akhir baris; /* */ adalah blok.
Gaya komentar mana yang diubah alat menjadi dokumentasi API?
Difficulty 1/5 · 100 coins + a small bonus on first completion today
Javadoc /** */ dengan @param/@return menghasilkan dokumentasi API.
Menambahkan komentar penjelas di samping rumus aktif yang tidak berubah memperbaiki perhitungannya.
Difficulty 1/5 · 100 coins + a small bonus on first completion today
Salah: komentar penjelas bukan pernyataan. Menonaktifkan (commenting out) sebuah pernyataan dapat mengubah perilaku, tetapi hal itu mengubah bagian mana dari kode yang aktif.
Komentar baik menjelaskan MENGAPA, daripada mengulang apa yang kode lakukan dengan jelas.
Difficulty 1/5 · 100 coins + a small bonus on first completion today
Komentari niatnya, bukan hal yang jelas.
Periksa dokumentasi terhadap implementasi
- Misalkan komentar menjanjikan bahwa jari-jari negatif ditolak, tetapi penjaga dihapus. Dokumentasi kini menjadi palsu meskipun masih berhasil digenerate; uji input negatif serta jari-jari biasa.
- Saat perilaku berubah, perbarui implementasi, pengecekannya, dan dokumentasinya secara bersamaan. Penggeneratoran halaman API memverifikasi sintaks dokumentasi, bukan kebenaran setiap klaim di dalamnya.
/** Returns an area. @param r radius @return area */ tidak meletakkan tag blok pada awal baris yang diperlukan. Gunakan bentuk multi-baris di atas, lalu periksa bagian parameter dan return yang dihasilkan. Komentar penjelasan biasa bukanlah perbaikan yang dapat dieksekusi.
Komentar yang berguna atau tidak?
Komentar baik menjelaskan niat, bukan hal yang jelas. Urutkan masing-masing.
Prediksi penugasan yang dikomentari
- Mulai dengan
int x = 1;. Dengan baris aktifx = 5;, mencetak x menghasilkan 5; menggantinya dengan// x = 5;akan mencetak 1. Mengubah mana yang menjadi baris aktif berbeda dengan menambahkan catatan di samping baris yang tidak berubah. - Tinjau tiga pertanyaan secara terpisah: apakah perhitungan aktif benar, apakah komentar menjelaskan hal itu dengan akurat, dan apakah tag Javadoc diterjemahkan ke bagian yang dimaksud? Kompilasi sukses tidak menjawab ketiga hal tersebut.
Komentar menjelaskan kode kepada pembaca. Delimiter dapat mengecualikan pernyataan, sedangkan catatan di samping kode aktif tidak memperbaiki perhitungan. Tag blok Javadoc dimulai pada baris terpisah; pastikan kontrak terdokumentasi konsisten dengan implementasi.
For a price of 100, type the amount paid after a ten percent discount.
Difficulty 1/5 · 100 coins + a small bonus on first completion today
The intended payment is 100−10=90. The misleading comment does not make the original expression calculate 90.
int x = 1; diikuti oleh // x = 5; pada baris terpisah. Nilai x berapakah yang dicetak?
Difficulty 2/5 · 140 coins + a small bonus on first completion today
Penugasan ke 5 dikecualikan oleh komentar satu baris; x tetap 1.