Komen dalam Java: tidak semuanya begitu mudah

pengenalan

Komen - nampaknya ia mungkin lebih mudah, dan mengapa menulis keseluruhan artikel. Tetapi ia tidak semudah itu. Seperti yang bos saya katakan, sesiapa sahaja boleh menulis kod, tetapi menulis komen yang baik adalah sukar. Kebanyakan kursus bahasa bermula dengan Hello World tradisional. Malah dalam Tutorial Oracle, dalam bahagian "Bermula", kita mulakan dengan "Hello World!" Permohonan . Dan dari baris pertama kod kita melihatnya - komen Java. Kepentingan mereka juga ditekankan oleh fakta bahawa dalam dokumen penting seperti Konvensyen Kod Java, ulasan diberikan bahagian yang berasingan: Komen . Menurut dokumentasi, komen dalam Java dibahagikan kepada dua jenis:

• ulasan pelaksanaan (atau ulasan kod);
• mendokumentasikan komen.

Komen kod digunakan untuk menerangkan baris/blok individu, dan komen dokumentasi digunakan untuk menerangkan spesifikasi kod (antara mukanya) bebas daripada pelaksanaannya. Komen Java diabaikan oleh pengkompil kerana mereka masuk akal kepada pembangun, bukan pengguna. Oleh itu, anda boleh mengurangkan saiz kelas yang disusun.

Komen kod Java

Dari namanya jelas bahawa ulasan ini berkaitan dengan kod dan harus mencerminkan ciri-cirinya. Komen kod ialah:

• Huruf kecil (iaitu diterangkan dalam satu baris)

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




• Blok (iaitu mereka digambarkan sebagai satu blok keseluruhan, kerana mereka tidak muat pada satu baris)

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

Ciri menarik ulasan blok ialah jika kita memulakannya dengan “ /*- ” (iaitu menambah tanda tolak selepas asterisk), maka teks ulasan blok ini tidak akan diformatkan. Menarik, tetapi dengan bantuan komen tertentu anda boleh memberikan beberapa petunjuk IDE. Contohnya, menggunakan ulasan sebaris " //@formatter:on " dan " //@formatter:off " dalam Eclipse IDE anda boleh melumpuhkan pemformatan untuk bahagian kod. Anda perlu menggunakan komen dengan berhati-hati dan hanya jika perlu. Sebagai contoh, anda boleh membaca artikel mengenai topik ini: "Jangan tulis ulasan pada kod!" . Terdapat sebuah buku hebat yang dipanggil Kod Bersih: Mencipta, Menganalisis, dan Memfaktorkan semula oleh Robert Martin. Ia mempunyai bab "Ulasan" yang berasingan. Sebagai epigraf untuk bab ini, petikan yang sama hebatnya: "Jangan ulas kod buruk—tulis semula" daripada Brian W. Kernighan dan P. J. Plower. Bab ini boleh didapati di Buku Google . Makna umum boleh dinyatakan dalam satu petikan daripada beliau:

Setiap kali anda mengulas, tersentak dan berasa seperti gagal."

Jelas bahawa tidak ada kebenaran mutlak, dan kadangkala komen diperlukan. Tetapi sentiasa ada pilihan, dan komen yang tidak perlu perlu dilawan. Bab ini juga menyebut ulasan luar biasa, TODO:

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

Intinya ialah mereka boleh dikendalikan dengan cara yang istimewa dalam IDE. Sebagai contoh, dalam IDEA ia dikumpulkan pada tab berasingan, di mana anda boleh melihatnya: Dan kusut kecil dengan ulasan: Baris "http://google.com" ialah baris yang sah di dalam kaedah, kerana http di sini sebenarnya adalah tag, dan kemudian ulasan. Selalunya banyak ulasan boleh pergi daripada komen kod kepada komen dokumentasi, yang akan kita bincangkan kemudian.

Komen untuk dokumentasi

Komen dokumentasi menerangkan API awam. API ialah antara muka pengaturcaraan aplikasi, iaitu kelas dan kaedah yang tersedia kepada pembangun lain untuk melakukan sebarang tindakan. Ringkasnya, ulasan ini harus menjelaskan mengapa kelas dan pakej ini atau itu dicipta dan apa yang dilakukan oleh kaedah ini atau itu. Anda juga boleh menerangkan medan kelas jika perlu. Inilah yang kami lihat dalam petua alat IDE kami, yang dibentangkan sebagai JavaDoc. Sebagai contoh: Jika kita pergi ke kaedah ini, kita boleh melihat dari mana teks ini berasal: Sekali lagi, lihat Konvensyen Kod Java: Konvensyen Kod tentang cara memformat JavaDoc dengan betul . Ia agak serupa dengan komen sekat, tetapi bukannya satu asterisk (bukan Asterix)) dua digunakan. Contoh JavaDoc diberikan di atas. Tidak ada gunanya menerangkan semua kemungkinan, kerana ini sudah ditulis dalam dokumentasi Oracle rasmi. Oleh itu, kami melihat semua yang kami perlukan dalam dokumentasi JavaDoc rasmi , bahagian "Penerangan Teg". Oracle juga mempunyai tutorial berasingan mengenai topik ini: Cara Menulis Komen Dokumen untuk Alat Javadoc . Petua alat dalam IDE bagus, tetapi ia sebenarnya dokumen atas sebab tertentu. Berdasarkan ulasan JavaDoc ini, dokumentasi dihasilkan. Terdapat utiliti javadoc khas untuk ini . Seperti yang dapat kita lihat, Tutorial itu bercakap tentang perkara ini. Penerangan tentang cara menggunakannya ada di tapak web Oracle rasmi untuk JavaDoc . Untuk melihat sendiri rupa ini, anda boleh mencipta subdirektori dalam direktori dengan nama pakej, contohnya: test . Buat kelas mudah dengan ulasan di dalamnya. Sebagai contoh:

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);
  }
}

Selepas ini, kami boleh menjalankan arahan berikut dari direktori yang mengandungi direktori pakej kami: javadoc -d ./test test Selepas ini, kami akan melihat proses penjanaan dokumentasi. Dan kemudian kita boleh membuka index.html untuk melihat dokumen yang dihasilkan. Anda akan sering melihat dokumentasi API disiarkan. Contohnya, Spring Framework API .

Kesimpulan

Seperti yang kita dapat lihat, perkara yang kelihatan mudah seperti komen ternyata menjadi lebih rumit dalam realiti. Oleh itu, jika anda meluangkan sedikit masa untuk komen dan mengikutinya, kod anda akan menjadi lebih baik dan anda akan menjadi lebih berharga sebagai pengaturcara. #Viacheslav