/ ** dan / * di Komentar Java


192

Apa bedanya

/**
 * comment
 *
 *
 */

dan

/*
 * 
 * comment
 *
 */

di Jawa? Kapan saya harus menggunakannya?

Jawaban:


243

Bentuk pertama disebut Javadoc . Anda menggunakan ini ketika Anda sedang menulis API formal untuk kode Anda, yang dihasilkan oleh javadocalat. Sebagai contoh, halaman Java 7 API menggunakan Javadoc dan dihasilkan oleh alat itu.

Beberapa elemen umum yang akan Anda lihat di Javadoc termasuk:

  • @param: ini digunakan untuk menunjukkan parameter apa yang diteruskan ke metode, dan nilai apa yang diharapkan dari mereka

  • @return: ini digunakan untuk menunjukkan hasil apa yang akan diberikan metode ini

  • @throws: ini digunakan untuk menunjukkan bahwa metode melempar pengecualian atau kesalahan dalam hal input tertentu

  • @since: ini digunakan untuk menunjukkan versi Java paling awal yang tersedia di kelas atau fungsi ini

Sebagai contoh, inilah Javadoc untuk comparemetode Integer:

/**
 * Compares two {@code int} values numerically.
 * The value returned is identical to what would be returned by:
 * <pre>
 *    Integer.valueOf(x).compareTo(Integer.valueOf(y))
 * </pre>
 *
 * @param  x the first {@code int} to compare
 * @param  y the second {@code int} to compare
 * @return the value {@code 0} if {@code x == y};
 *         a value less than {@code 0} if {@code x < y}; and
 *         a value greater than {@code 0} if {@code x > y}
 * @since 1.7
 */
public static int compare(int x, int y) {
    return (x < y) ? -1 : ((x == y) ? 0 : 1);
}

Bentuk kedua adalah komentar blok (multi-line). Anda menggunakan ini jika Anda ingin memiliki beberapa baris dalam komentar.

Saya akan mengatakan bahwa Anda hanya ingin menggunakan formulir yang terakhir dengan hemat ; yaitu, Anda tidak ingin membebani kode Anda dengan komentar blokir yang tidak menjelaskan perilaku apa yang seharusnya dimiliki oleh fungsi metode / kompleks.

Karena Javadoc lebih deskriptif dari keduanya, dan Anda dapat menghasilkan dokumentasi yang sebenarnya sebagai hasil menggunakannya, menggunakan Javadoc akan lebih disukai daripada komentar blok sederhana.


35
Manfaat lain yang bagus dari menggunakan Javadoc daripada komentar blok sederhana adalah bahwa ketika Anda meletakkan komentar Javadoc sebelum elemen Java (mis. Tanda tangan metode, deklarasi lapangan, kelas dll.) Ini memungkinkan IDE - setidaknya Eclipse pasti - untuk menampilkan komentar Anda (mis. di tooltip) saat Anda menggerakkan kursor - atau mengarahkan kursor dengan mouse - pada referensi ke elemen Java tersebut.
SantiBailors

Apakah saya tetap bisa menggunakan komentar java doc untuk variabel?
the_prole

@ the_prole: Anda bisa, tapi saya tidak melihat banyak nilai di dalamnya kecuali itu adalah bagian dari paket jenis Konstanta. Bahkan kemudian, komentar in-line lebih berharga dalam pengalaman saya.
Makoto

136

Untuk bahasa pemrograman Java , tidak ada perbedaan antara keduanya. Java memiliki dua jenis komentar: komentar tradisional ( /* ... */) dan komentar end-of-line ( // ...). Lihat Spesifikasi Bahasa Jawa . Jadi, untuk bahasa pemrograman Java, keduanya /* ... */dan/** ... */ merupakan contoh komentar tradisional, dan mereka berdua diperlakukan persis sama oleh compiler Java, yaitu, mereka diabaikan (atau lebih tepatnya: mereka diperlakukan sebagai ruang putih).

Namun, sebagai programmer Java, Anda tidak hanya menggunakan kompiler Java. Anda menggunakan seluruh rantai alat, yang meliputi misalnya kompiler, IDE, sistem build, dll. Dan beberapa alat ini menginterpretasikan hal-hal berbeda dari kompiler Java. Secara khusus, /** ... */komentar ditafsirkan oleh alat Javadoc, yang termasuk dalam platform Java dan menghasilkan dokumentasi. Alat Javadoc akan memindai file sumber Java dan menafsirkan bagian-bagian antara /** ... */sebagai dokumentasi.

Ini mirip dengan tag suka FIXMEdan TODO: jika Anda menyertakan komentar suka // TODO: fix thisatau // FIXME: do that, sebagian besar IDE akan menyorot komentar tersebut sehingga Anda tidak melupakannya. Tapi untuk Jawa, itu hanya komentar.


48
+1 untuk membuat perbedaan penting bahwa sintaksis Javadoc bukan bagian dari bahasa, yang saat ini tidak dijawab oleh jawaban lain.
Chris Hayes

1
Inilah sebabnya mengapa Anda dapat memiliki proyek yang mengkompilasi dengan baik di Maven tetapi segera setelah Anda memutuskan untuk melampirkan JavaDocs mulai mengeluh karena javadocalat tidak dapat menafsirkan sesuatu.
Kapten Man

19

Yang pertama adalah komentar Javadoc. Mereka dapat diproses oleh javadocalat untuk menghasilkan dokumentasi API untuk kelas Anda. Yang kedua adalah komentar blok normal.


14

Membaca bagian 3.7 JLS baik menjelaskan semua yang perlu Anda ketahui tentang komentar di Jawa.

Ada dua jenis komentar:

  • / * teks * /

Komentar tradisional: semua teks dari karakter ASCII / * ke karakter ASCII * / diabaikan (seperti dalam C dan C ++).

  • //teks

Komentar akhir baris: semua teks dari karakter ASCII // hingga akhir baris diabaikan (seperti dalam C ++).


Tentang pertanyaan Anda,

Yang pertama

/**
 *
 */

digunakan untuk mendeklarasikan Teknologi Javadoc .

Javadoc adalah alat yang mem-parsing deklarasi dan dokumentasi komentar dalam satu set file sumber dan menghasilkan satu set halaman HTML yang menggambarkan kelas, antarmuka, konstruktor, metode, dan bidang. Anda dapat menggunakan doclet Javadoc untuk menyesuaikan output Javadoc. Doclet adalah program yang ditulis dengan API Doclet yang menentukan konten dan format output yang akan dihasilkan oleh alat. Anda dapat menulis dokumen untuk menghasilkan segala jenis output file teks, seperti HTML, SGML, XML, RTF, dan MIF. Oracle menyediakan dokumen standar untuk menghasilkan dokumentasi API format HTML. Doclets juga dapat digunakan untuk melakukan tugas-tugas khusus yang tidak terkait dengan pembuatan dokumentasi API.

Untuk informasi lebih lanjut tentang Docletmerujuk ke API .

Yang kedua, seperti yang dijelaskan dengan jelas dalam JLS, akan mengabaikan semua teks di antara /*dan */dengan demikian digunakan untuk membuat komentar multiline.


Beberapa hal lain yang mungkin ingin Anda ketahui tentang komentar di Jawa

  • Komentar jangan bersarang.
  • /* and */tidak memiliki arti khusus dalam komentar yang dimulai dengan //.
  • //tidak memiliki arti khusus dalam komentar yang dimulai dengan /* or /**.
  • Tata bahasa leksikal menyiratkan bahwa komentar tidak terjadi dalam literal karakter ( §3.10.4 ) atau literal string ( §3.10.5 ).

Dengan demikian, teks berikut adalah satu komentar lengkap:

/* this comment /* // /** ends here: */

8

Saya kira jawaban yang ada tidak cukup menjawab bagian pertanyaan ini:

Kapan saya harus menggunakannya?

Jika Anda menulis API yang akan diterbitkan atau digunakan kembali dalam organisasi Anda, Anda harus menulis komentar Javadoc yang komprehensif untuk setiap publickelas, metode, dan bidang, serta protectedmetode dan bidang non- finalkelas. Javadoc harus mencakup semua yang tidak dapat disampaikan oleh metode tanda tangan, seperti prasyarat, postkondisi, argumen yang valid, pengecualian runtime, panggilan internal, dll.

Jika Anda menulis API internal (yang digunakan oleh bagian berbeda dari program yang sama), Javadoc bisa dibilang kurang penting. Tetapi untuk kepentingan programmer pemeliharaan, Anda harus tetap menulis Javadoc untuk metode atau bidang apa pun di mana penggunaan atau makna yang benar tidak segera terlihat.

"Fitur pembunuh" dari Javadoc adalah bahwa ia terintegrasi dengan Eclipse dan IDE lainnya. Pengembang hanya perlu mengarahkan kursor mouse mereka ke pengenal untuk mempelajari semua yang perlu mereka ketahui tentang hal itu. Mengacu pada dokumentasi secara terus-menerus menjadi sifat kedua bagi pengembang Java yang berpengalaman, yang meningkatkan kualitas kode mereka sendiri. Jika API Anda tidak didokumentasikan dengan Javadoc, pengembang yang berpengalaman tidak ingin menggunakannya.


4

Komentar dalam daftar Kode Java berikut adalah karakter yang diklik:

/** 
 * The HelloWorldApp class implements an application that
 * simply displays "Hello World!" to the standard output.
 */
class HelloWorldApp {
    public static void main(String[] args) {
        System.out.println("Hello World!"); //Display the string.
    }
}

Bahasa Jawa mendukung tiga jenis komentar:

/* text */

Kompiler mengabaikan segalanya mulai dari /*hingga */.

/** documentation */

Ini menunjukkan komentar dokumentasi (komentar dokumen, singkatnya). Kompiler mengabaikan komentar semacam ini, sama seperti mengabaikan komentar yang menggunakan /*dan */. Alat javadoc JDK menggunakan komentar doc ketika menyiapkan dokumentasi yang dihasilkan secara otomatis.

// text

Kompilator mengabaikan semuanya mulai //dari akhir baris.

Sekarang tentang kapan Anda harus menggunakannya:

Gunakan // textketika Anda ingin mengomentari satu baris kode.

Menggunakan /* text */ ketika Anda ingin mengomentari banyak baris kode.

Gunakan /** documentation */ ketika Anda ingin menambahkan beberapa info tentang program yang dapat digunakan untuk pembuatan dokumentasi program secara otomatis.


3

Yang pertama adalah untuk Javadoc Anda mendefinisikan di atas kelas, antarmuka, metode dll. Anda dapat menggunakan Javadoc seperti namanya untuk mendokumentasikan kode Anda tentang apa yang dilakukan kelas atau metode apa dll dan menghasilkan laporan tentang itu.

Yang kedua adalah komentar blok kode. Katakan misalnya Anda memiliki beberapa blok kode yang Anda tidak ingin ditafsirkan oleh kompiler maka Anda menggunakan komentar blok kode.

yang lain adalah // ini yang Anda gunakan pada level pernyataan untuk menentukan apa yang seharusnya dilakukan oleh baris kode selanjutnya.

Ada beberapa yang lain juga seperti // TODO, ini akan menandai bahwa Anda ingin melakukan sesuatu nanti di tempat itu

// FIXME yang dapat Anda gunakan ketika Anda memiliki solusi sementara tetapi Anda ingin mengunjungi nanti dan membuatnya lebih baik.

Semoga ini membantu


0
  • Satu komentar misalnya: // komentar
  • Komentar Multi Line misalnya: / * komentar * /
  • komentar javadoc misalnya: / ** komentar * /

4
Ini tidak menambahkan apa pun dari jawaban yang ada.
shmosel

1
@shosel tidak, itu meringkas mereka tho.
Det

-2

Java mendukung dua jenis komentar:

  • /* multiline comment */: Kompilator mengabaikan semuanya dari /*hingga */. Komentar dapat menjangkau beberapa baris.

  • // single line: Compiler mengabaikan semuanya mulai //dari akhir baris.

Beberapa alat seperti javadoc menggunakan komentar multiline khusus untuk tujuan mereka. Sebagai contoh /** doc comment */adalah komentar dokumentasi yang digunakan oleh javadoc ketika menyiapkan dokumentasi yang dibuat secara otomatis, tetapi untuk Java itu adalah komentar multiline sederhana.


12
Bahasa Jawa hanya mendukung dua jenis komentar. Komentar dalam bentuk /** .. */hanyalah komentar multiline biasa, dan karakter pertama di dalamnya adalah tanda bintang.
Chris Hayes
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.