Komentar di Jawa: tidak semuanya sesederhana itu

Perkenalan

Komentar - tampaknya ini bisa lebih sederhana, dan mengapa menulis artikel lengkap. Tapi itu tidak sesederhana itu. Seperti yang dikatakan bos saya, siapa pun bisa menulis kode, tetapi menulis komentar yang bagus itu sulit. Kebanyakan kursus bahasa dimulai dengan Hello World tradisional. Bahkan dalam Tutorial Oracle, di bagian "Memulai", kita mulai dengan kalimat "Halo Dunia!" Aplikasi . Dan dari baris kode pertama kita melihatnya - komentar Java. Pentingnya hal ini juga ditekankan oleh fakta bahwa dalam dokumen penting seperti Konvensi Kode Java, komentar diberikan pada bagian terpisah: Komentar . Menurut dokumentasinya, komentar di Java dibagi menjadi dua jenis:

• komentar implementasi (atau komentar kode);
• mendokumentasikan komentar.

Komentar kode digunakan untuk mendeskripsikan baris/blok individual, dan komentar dokumentasi digunakan untuk mendeskripsikan spesifikasi kode (antarmukanya) terlepas dari implementasinya. Komentar Java diabaikan oleh kompiler karena mereka masuk akal bagi pengembang, bukan pengguna. Oleh karena itu, Anda dapat mengurangi ukuran kelas yang dikompilasi.

Komentar kode Java

Dari namanya jelas bahwa komentar ini berkaitan dengan kode dan harus mencerminkan fitur-fiturnya. Komentar kode adalah:

• Huruf kecil (yaitu dijelaskan dalam satu baris)

  // Строчный комментарий
  System.out.println("Hello, World!");




• Blok (yaitu digambarkan sebagai satu blok utuh, karena tidak muat dalam satu baris)

  /*
   * Блочный комментарий
   */
  System.out.println("Hello");

Fitur menarik dari komentar blok adalah jika kita memulainya dengan “ /*- ” (yaitu menambahkan tanda minus setelah tanda bintang), maka teks komentar blok ini tidak akan diformat. Menarik, tetapi dengan bantuan komentar tertentu Anda bisa memberikan beberapa petunjuk IDE. Misalnya, dengan menggunakan komentar sebaris " //@formatter:on " dan " //@formatter:off " di IDE Eclipse Anda dapat menonaktifkan pemformatan untuk bagian kode. Anda perlu menggunakan komentar dengan hemat dan hanya jika diperlukan. Misalnya, Anda dapat membaca artikel tentang topik ini: “Jangan menulis komentar pada kode!” . Ada buku bagus berjudul Clean Code: Creating, Analyzing, and Refactoring oleh Robert Martin. Ini memiliki bab terpisah "Komentar". Sebagai prasasti untuk bab ini, kutipan yang sama bagusnya: “Jangan mengomentari kode yang buruk—tulis ulang” dari Brian W. Kernighan dan P. J. Plough. Bab ini dapat ditemukan di Google Buku . Makna umum dapat diungkapkan dalam satu kutipan darinya:

Setiap kali Anda berkomentar, Anda meringis dan merasa gagal."

Jelas bahwa tidak ada kebenaran mutlak, dan terkadang diperlukan komentar. Namun selalu ada pilihan, dan komentar yang tidak perlu harus dilawan. Bab ini juga menyebutkan komentar yang tidak biasa, TODO:

// TODO: Добавить World
System.out.println("Hello, ");

Intinya bisa ditangani dengan cara khusus di IDE. Misalnya, di IDEA, mereka dikumpulkan di tab terpisah, tempat Anda dapat melihatnya: Dan teka-teki kecil dengan komentar: Baris “http://google.com” adalah baris yang valid di dalam metode, karena http di sini sebenarnya adalah sebuah tag, dan kemudian sebuah komentar. Seringkali banyak komentar dapat beralih dari komentar kode ke komentar dokumentasi, yang akan kita bahas nanti.

Komentar untuk dokumentasi

Komentar dokumentasi menjelaskan API publik. API adalah antarmuka pemrograman aplikasi, yaitu kelas dan metode yang tersedia bagi pengembang lain untuk melakukan tindakan apa pun. Singkatnya, komentar ini harus menjelaskan mengapa kelas dan paket ini atau itu dibuat dan apa yang dilakukan metode ini atau itu. Anda juga dapat menjelaskan bidang kelas jika perlu. Inilah yang kami lihat di tooltips IDE kami, yang disajikan sebagai JavaDoc. Misalnya: Jika kita mendalami metode ini, kita dapat melihat dari mana teks ini berasal: Sekali lagi, lihat Konvensi Kode Java: Konvensi Kode tentang cara memformat JavaDoc dengan benar . Mereka agak mirip dengan memblokir komentar, tetapi alih-alih satu tanda bintang (bukan Asterix)), dua tanda bintang digunakan. Contoh JavaDoc diberikan di atas. Tidak ada gunanya menjelaskan semua kemungkinan, karena ini sudah tertulis di dokumentasi resmi Oracle. Oleh karena itu, kami melihat semua yang kami butuhkan di dokumentasi resmi JavaDoc , bagian "Deskripsi Tag". Oracle bahkan memiliki tutorial terpisah tentang topik ini: Cara Menulis Komentar Dokumen untuk Alat Javadoc . Tooltip di IDE memang bagus, tetapi sebenarnya itu adalah dokumen karena suatu alasan. Berdasarkan komentar JavaDoc ini, dokumentasi dibuat. Ada utilitas javadoc khusus untuk ini . Seperti yang bisa kita lihat, Tutorial itu membicarakan hal ini. Penjelasan cara menggunakannya ada di situs resmi Oracle untuk JavaDoc . Untuk melihat sendiri seperti apa tampilannya, Anda dapat membuat subdirektori pada direktori tersebut dengan nama paketnya, misalnya: test . Buat kelas sederhana dengan komentar di dalamnya. Misalnya:

package test;

/**
 * This is a JavaDoc class comment
 */
public class JavaDocTest {

  /**
   * This is a JavaDoc public field comment
   */
  public static final String HELLO_MESSAGE = "Hello, World!";

  public static void main(String... args) {
    JavaDocTest.greetings();
  }

  /**
   * This is a JavaDoc public method comment
   */
  public static void greetings() {
    System.out.println(HELLO_MESSAGE);
  }
}

Setelah ini, kita dapat menjalankan perintah berikut dari direktori yang berisi direktori paket kita: javadoc -d ./test test Setelah ini, kita akan melihat proses pembuatan dokumentasi. Dan kemudian kita bisa membuka index.html untuk melihat dokumen yang dihasilkan. Anda akan sering melihat dokumentasi API diposting. Misalnya, API Kerangka Musim Semi .

Kesimpulan

Seperti yang bisa kita lihat, hal yang tampaknya sederhana seperti komentar ternyata jauh lebih rumit pada kenyataannya. Oleh karena itu, jika Anda meluangkan waktu untuk berkomentar dan mengikutinya, kode Anda akan lebih baik dan Anda akan lebih berharga sebagai seorang programmer. #Viacheslav