Mga komento sa Java: hindi lahat ay napakasimple

Panimula

Mga komento - mukhang mas simple ito, at bakit sumulat ng isang buong artikulo. Ngunit hindi ganoon kasimple. Tulad ng sinabi ng aking boss, kahit sino ay maaaring magsulat ng code, ngunit ang pagsulat ng isang magandang komento ay mahirap. Karamihan sa mga kurso sa wika ay nagsisimula sa tradisyonal na Hello World. Kahit sa Mga Tutorial sa Oracle, sa seksyong "Pagsisimula", nagsisimula tayo sa "Hello World!" Aplikasyon . At mula sa pinakaunang mga linya ng code ay nakikita natin ang mga ito - mga komento ng Java. Ang kanilang kahalagahan ay binibigyang-diin din ng katotohanan na sa isang mahalagang dokumento tulad ng Java Code Convention, ang mga komento ay binibigyan ng hiwalay na seksyon: Mga Komento . Ayon sa dokumentasyon, ang mga komento sa Java ay nahahati sa dalawang uri:

• komento sa pagpapatupad (o komento ng code);
• pagdodokumento ng komento.

Ginagamit ang mga komento ng code upang ilarawan ang mga indibidwal na linya/block, at ang mga komento sa dokumentasyon ay ginagamit upang ilarawan ang detalye ng code (interface nito) na hiwalay sa pagpapatupad nito. Ang mga komento sa Java ay hindi pinapansin ng compiler dahil may katuturan sila sa developer, hindi sa user. Samakatuwid, maaari mong bawasan ang laki ng mga pinagsama-samang klase.

Mga komento sa Java code

Mula sa pangalan ay malinaw na ang komentong ito ay nauugnay sa code at dapat ipakita ang mga tampok nito. Ang mga komento sa code ay:

• Maliit na titik (ibig sabihin, inilarawan sa isang linya)

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




• Block (ibig sabihin, ang mga ito ay inilarawan bilang isang buong bloke, dahil hindi sila magkasya sa isang linya)

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

Ang isang kawili-wiling tampok ng isang bloke na komento ay kung sisimulan natin ito sa " /*- " (ibig sabihin, magdagdag ng minus sign pagkatapos ng asterisk), kung gayon ang teksto ng bloke na komentong ito ay hindi ma-format. Kawili-wili, ngunit sa tulong ng ilang mga komento maaari kang magbigay ng ilang mga pahiwatig ng IDE. Halimbawa, gamit ang mga inline na komento " //@formatter:on " at " //@formatter:off " sa Eclipse IDE maaari mong i-disable ang pag-format para sa mga seksyon ng code. Kailangan mong gumamit ng mga komento nang matipid at kung kinakailangan lamang. Halimbawa, maaari kang magbasa ng isang artikulo sa paksang ito: "Huwag magsulat ng mga komento sa code!" . Mayroong isang mahusay na aklat na tinatawag na Clean Code: Creating, Analyzing, and Refactoring ni Robert Martin. Mayroon itong hiwalay na kabanata na "Mga Komento". Bilang isang epigraph sa kabanatang ito, isang mahusay na quote: "Huwag magkomento ng masamang code—isulat muli ito" mula kay Brian W. Kernighan at P. J. Plower. Ang kabanatang ito ay matatagpuan sa Google Books . Ang pangkalahatang kahulugan ay maaaring ipahayag sa isang quote mula sa kanya:

Sa tuwing magkokomento ka, nanginginig ka at pakiramdam mo ay nabigo ka."

Malinaw na walang ganap na katotohanan, at kung minsan ang mga komento ay kinakailangan. Ngunit palaging may mga pagpipilian, at ang mga hindi kinakailangang komento ay kailangang labanan. Binabanggit din ng kabanatang ito ang mga hindi pangkaraniwang komento, TODO:

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

Ang punto ng mga ito ay maaari silang pangasiwaan sa isang espesyal na paraan sa IDE. Halimbawa, sa IDEA, kinokolekta ang mga ito sa isang hiwalay na tab, kung saan maaari mong tingnan ang mga ito: At isang maliit na tagapagpaisip na may komento: Ang linyang "http://google.com" ay isang wastong linya sa loob ng pamamaraan, dahil Ang http dito ay talagang isang tag, at pagkatapos ay isang komento. Kadalasan maraming komento ang maaaring pumunta mula sa mga komento ng code hanggang sa mga komento sa dokumentasyon, na pag-uusapan natin sa ibang pagkakataon.

Mga komento para sa dokumentasyon

Inilalarawan ng mga komento sa dokumentasyon ang pampublikong API. Ang API ay ang application programming interface, iyon ay, ang mga klase at pamamaraang iyon na available sa iba pang mga developer para magsagawa ng anumang mga aksyon. Sa madaling salita, dapat ipaliwanag ng mga komentong ito kung bakit ito o ang klase at package na ito ay nilikha at kung ano ang ginagawa nito o ang pamamaraang iyon. Maaari mo ring ilarawan ang mga field ng klase kung kinakailangan. Ito mismo ang nakikita namin sa mga tooltip ng aming mga IDE, na naka-format bilang isang JavaDoc. Halimbawa: Kung pupunta tayo sa paraang ito, makikita natin kung saan nagmula ang tekstong ito: Muli, tingnan ang Java Code Convention: Code Convention sa kung paano maayos na i-format ang isang JavaDoc . Ang mga ito ay medyo katulad ng mga komento sa pagharang, ngunit sa halip na isang asterisk (hindi Asterix)) dalawa ang ginagamit. Ang isang halimbawa ng JavaDoc ay ibinigay sa itaas. Walang saysay na ilarawan ang lahat ng mga posibilidad, dahil nakasulat na ito sa opisyal na dokumentasyon ng Oracle. Samakatuwid, tinitingnan namin ang lahat ng kailangan mo sa opisyal na dokumentasyon ng JavaDoc , seksyong "Mga Paglalarawan ng Tag". Ang Oracle ay mayroon ding hiwalay na tutorial sa paksang ito: Paano Sumulat ng Mga Komento ng Doc para sa Javadoc Tool . Ang mga tooltip sa IDE ay maganda, ngunit ang mga ito ay talagang mga doc para sa isang dahilan. Batay sa mga komentong ito ng JavaDoc, nabuo ang dokumentasyon. Mayroong isang espesyal na javadoc utility para dito . Tulad ng nakikita natin, ang Tutorial na iyon ay nagsasalita tungkol dito. Ang isang paglalarawan kung paano ito gamitin ay nasa opisyal na website ng Oracle para sa JavaDoc . Upang makita mismo kung ano ang hitsura nito, maaari kang lumikha ng isang subdirectory sa direktoryo na may pangalan ng package, halimbawa: test . Gumawa ng isang simpleng klase na may mga komento dito. Halimbawa:

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

Pagkatapos nito, maaari naming patakbuhin ang sumusunod na command mula sa direktoryo na naglalaman ng aming direktoryo ng package: javadoc -d ./test test Pagkatapos nito, makikita natin ang proseso ng pagbuo ng dokumentasyon. At pagkatapos ay maaari naming buksan ang index.html upang makita ang nabuong dokumento. Madalas mong makikita ang dokumentasyon ng API na nai-post. Halimbawa, Spring Framework API .

Konklusyon

Tulad ng nakikita natin, ang isang tila simpleng bagay tulad ng mga komento ay lumalabas na mas kumplikado sa katotohanan. Samakatuwid, kung gumugugol ka ng ilang oras sa mga komento at sundin ang mga ito, ang iyong code ay magiging mas mahusay at ikaw ay magiging mas mahalaga bilang isang programmer. #Viacheslav