Komentar ing Jawa: ora kabeh dadi prasaja

Pambuka

Komentar - koyone luwih gampang, lan kenapa nulis artikel lengkap. Nanging iku ora sing prasaja. Kaya sing diomongake bosku, sapa wae bisa nulis kode, nanging nulis komentar sing apik iku angel. Umume kursus basa diwiwiti kanthi Hello World tradisional. Malah ing Tutorial Oracle, ing bagean "Miwiti", kita miwiti karo "Hello World!" Aplikasi . Lan saka baris pisanan kode kita ndeleng wong - komentar Jawa. Pentinge uga ditekanake yen ing dokumen penting kaya Java Code Convention, komentar diwenehi bagean sing kapisah: Komentar . Miturut dokumentasi, komentar ing Jawa dipérang dadi rong jinis:

• komentar implementasi (utawa komentar kode);
• komentar dokumentasi.

Komentar kode digunakake kanggo njlèntrèhaké baris individu / pamblokiran, lan komentar dokumentasi digunakake kanggo njlèntrèhaké specification saka kode (antarmuka sawijining) independen saka implementasine. Komentar Jawa ora digatèkaké déning compiler amarga padha nggawe pangertèn kanggo pangembang, ora pangguna. Mula, sampeyan bisa nyuda ukuran kelas sing dikompilasi.

Komentar kode Jawa

Saka jeneng kasebut jelas yen komentar iki ana hubungane karo kode kasebut lan kudu nggambarake fitur-fitur kasebut. Komentar kode yaiku:

• Huruf cilik (yaiku diterangake ing siji baris)

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




• Blok (yaiku digambarake minangka blok kabeh, amarga ora cocog karo siji baris)

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

Fitur menarik saka komentar pemblokiran yaiku yen kita miwiti nganggo " /*- " (yaiku nambah tandha minus sawise tanda bintang), banjur teks komentar blok iki ora bakal diformat. Interesting, nanging karo bantuan saka komentar tartamtu sampeyan bisa menehi sawetara pitunjuk IDE. Contone, nggunakake komentar inline " //@formatter:on " lan " //@formatter: off " ing Eclipse IDE sampeyan bisa mateni format kanggo bagean kode. Sampeyan kudu nggunakake komentar sparingly lan mung yen perlu. Contone, sampeyan bisa maca artikel babagan topik iki: "Aja nulis komentar babagan kode!" . Ana buku gedhe sing diarani Kode Bersih: Nggawe, Nganalisa, lan Refactoring dening Robert Martin. Wis bab kapisah "Komentar". Minangka epigraph kanggo bab iki, kutipan merata apik banget: "Aja komentar kode ala - nulis maneh" saka Brian W. Kernighan lan P. J. Plower. Bab iki bisa ditemokake ing Google Books . Makna umum bisa diungkapake ing salah sawijining kutipan saka dheweke:

Saben sampeyan nulis komentar, meringis lan rumangsa gagal."

Cetha yen ora ana bebener sing mutlak, lan kadhangkala komentar perlu. Nanging mesthi ana pilihan, lan komentar sing ora perlu kudu dilawan. Bab iki uga nyebutake komentar sing ora biasa, TODO:

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

Titik kasebut yaiku bisa ditangani kanthi cara khusus ing IDE. Contone, ing IDEA diklumpukake ing tab sing kapisah, ing ngendi sampeyan bisa ndeleng: Lan puzzler cilik karo komentar: Baris "http://google.com" iku baris bener nang cara, amarga http kene bener tag, lan banjur komentar. Asring akeh komentar bisa pindhah saka komentar kode menyang komentar dokumentasi, sing bakal kita bahas mengko.

Komentar kanggo dokumentasi

Komentar dokumentasi njlèntrèhaké API umum. API minangka antarmuka pemrograman aplikasi, yaiku, kelas lan metode sing kasedhiya kanggo pangembang liyane kanggo nindakake tindakan apa wae. Ing cendhak, komentar iki kudu nerangake apa iki utawa sing kelas lan paket digawe lan apa iki utawa cara iki. Sampeyan uga bisa njlèntrèhaké lapangan kelas yen perlu. Iki persis sing kita deleng ing tooltips IDE kita, sing ditampilake minangka JavaDoc. Tuladhane: Yen kita pindhah menyang metode iki, kita bisa ndeleng saka endi teks iki: Maneh, deleng Java Code Convention: Code Convention babagan cara ngowahi format JavaDoc kanthi bener . Padha kaya kanggo mblokir komentar, nanging tinimbang siji asterisk (ora Asterix)) loro digunakake. Conto JavaDoc diwenehi ing ndhuwur. Ora ana gunane kanggo njlentrehake kabeh kemungkinan, amarga iki wis ditulis ing dokumentasi Oracle resmi. Mulane, kita katon ing kabeh sing perlu ing resmi JavaDoc dokumentasi , bagean "Tag Description". Oracle malah duwe tutorial kapisah babagan topik iki: Cara Nulis Komentar Doc kanggo Alat Javadoc . Tooltips ing IDE apik, nanging padha bener docs kanggo alesan. Adhedhasar komentar JavaDoc iki, dokumentasi digawe. Ana utilitas javadoc khusus kanggo iki . Minangka kita bisa ndeleng, Tutorial iki ngomong babagan iki. Katrangan babagan cara nggunakake ana ing situs web Oracle resmi kanggo JavaDoc . Kanggo ndeleng dhewe kaya apa iki, sampeyan bisa nggawe subdirektori ing direktori kanthi jeneng paket, contone: test . Nggawe kelas prasaja kanthi komentar. Tuladhane:

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

Sawise iki, kita bisa mbukak printah ing ngisor iki saka direktori sing ngemot direktori paket kita: javadoc -d ./test test Sawise iki, kita bakal weruh proses generasi dokumentasi. Banjur kita bisa mbukak index.html kanggo ndeleng dokumen sing digawe. Sampeyan bakal kerep ndeleng dokumentasi API dikirim. Contone, Spring Framework API .

Kesimpulan

Kaya sing bisa dideleng, perkara sing katon gampang kaya komentar dadi luwih rumit ing kasunyatan. Mulane, yen sampeyan nglampahi sawetara wektu kanggo komentar lan ngetutake, kode sampeyan bakal luwih apik lan sampeyan bakal luwih berharga minangka programmer. #Viacheslav