Java тилиндеги комментарийлер: баары жөнөкөй эмес

Киришүү

Комментарийлер - бул жөнөкөй болушу мүмкүн окшойт, жана эмне үчүн бүтүндөй макала жазуу. Бирок бул анчалык жөнөкөй эмес. Жетекчим айткандай, каалаган адам code жаза алат, бирок жакшы комментарий жазуу кыйын. Көпчүлүк тил курстары салттуу Hello World менен башталат. Жада калса Oracle Tutorials, "Баштоо" бөлүмүндө биз "Салам дүйнө!" деп баштайбыз. Колдонмо . Жана codeдун эң биринчи саптарынан биз аларды көрөбүз - Java комментарийлери. Алардын маанилүүлүгү Java Code Convention сыяктуу маанилүү documentте комментарийлерге өзүнчө бөлүм берилгени менен да баса белгиленет: Комментарийлер . Документке ылайык, Java тorндеги комментарийлер эки түргө бөлүнөт:

• ишке ашыруу боюнча комментарий (же code комментарий);
• комментарий documentтештирүү.

Код комментарийлери жеке саптарды/блокторду сүрөттөө үчүн колдонулат, ал эми documentтик комментарийлер codeдун спецификациясын (анын интерфейсин) анын ишке ашырылышынан көз карандысыз сүрөттөө үчүн колдонулат. Java комментарийлери компилятор тарабынан этибарга алынbyte, анткени алар колдонуучуга эмес, иштеп чыгуучуга маани берет. Ошондуктан, сиз түзүлгөн класстардын көлөмүн азайтууга болот.

Java codeун комментарийлери

Атынан көрүнүп тургандай, бул комментарий codeго тиешелүү жана анын өзгөчөлүктөрүн чагылдырышы керек. Код комментарийлери:

• Кичи тамга (б.а. бир сапта сүрөттөлгөн)

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




• Блок (б.а. алар бүтүндөй блок катары сүрөттөлөт, анткени алар бир сызыкка туура келбейт)

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

Блок комментарийинин кызыктуу өзгөчөлүгү, эгерде биз аны “ /*- ” менен баштасак (б.а. жылдызчадан кийин минус белгисин кошсок), анда бул блок комментарийинин тексти форматталbyte. Кызыктуу, бирок кээ бир комментарийлердин жардамы менен сиз IDE боюнча кээ бир кеңештерди бере аласыз. Мисалы, Eclipse IDEдеги " //@formatter:on " жана " //@formatter:off " inline комментарийлерин колдонуп, codeдун бөлүмдөрү үчүн форматтоону өчүрө аласыз. Комментарийлерди үнөмдүү жана зарыл учурларда гана колдонуу керек. Мисалы, сиз бул темадагы макаланы окуй аласыз: "Кодго комментарий жазбаңыз!" . Роберт Мартиндин "Таза code: түзүү, анализдөө жана рефакторинг" деген сонун китеби бар . Ал өзүнчө "Комментарийлер" бөлүмү бар. Бул бөлүмдүн эпиграфы катары, ошондой эле эң сонун цитата: Брайан В. Керниган менен П. Дж. Плоуэрден: “Жаман codeго комментарий бербе, аны кайра жаз”. Бул бөлүмдү Google Китептерден тапса болот . Анын жалпы маанисин бир цитата менен айтса болот:

Комментарий берген сайын, ирмеп, өзүңүздү ийгorксиз сезиңиз."

Абсолюттук чындык жок экени түшүнүктүү, кээде комментарийлер керек болот. Бирок ар дайым варианттар бар, керексиз комментарийлер менен күрөшүү керек. Бул бөлүмдө ошондой эле адаттан тыш комментарийлер айтылат, TODO:

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

Алардын мааниси, аларды IDEде өзгөчө ыкма менен иштетүүгө болот. Мисалы, IDEAда алар өзүнчө өтмөктө чогултулган, анда сиз аларды көрө аласыз: Ал эми комментарийи бар кичинекей табышмак: “http://google.com” сызыгы методдун ичиндеги жарактуу сызык, анткени http бул жерде чындыгында тег, анан комментарий. Көбүнчө көптөгөн комментарийлер codeдук комментарийлерден documentтик комментарийлерге чейин өтүшү мүмкүн, алар жөнүндө кийинчерээк сүйлөшөбүз.

Документ үчүн комментарийлер

Документтердин комментарийлери жалпыга ачык API сүрөттөйт. API - бул колдонмо программалоо интерфейси, башкача айтканда, башка иштеп чыгуучуларга кандайдыр бир аракеттерди жасоо үчүн жеткorктүү болгон класстар жана методдор. Кыскасы, бул комментарийлер тигил же бул класс жана пакет эмне үчүн түзүлгөнүн жана тигил же бул методдун эмне кыларын түшүндүрүшү керек. Керек болсо класс талааларын да сүрөттөй аласыз. Бул JavaDoc катары форматталган биздин IDE куралдардын кеңештеринде дал ушул нерсени көрөбүз. Мисалы: Бул ыкмага кирсек, бул тексттин кайдан келгенин көрө алабыз: Дагы бир жолу, Java Code Convention: Code Convention JavaDoc файлын кантип туура форматтоо керек экенин караңыз . Алар комментарийлерди бөгөт коюуга бир аз окшош, бирок бир жылдызчанын ордуна (Asterix эмес) экөө колдонулат. Мисал JavaDoc жогоруда берилген. Бардык мүмкүнчүлүктөрдү сүрөттөп берүүнүн кереги жок, анткени бул тууралуу расмий Oracle documentтеринде жазылган. Ошондуктан, биз расмий JavaDoc documentтеринде керектүү нерселердин баарын карап чыгабыз , бөлүмдүн "Tag сүрөттөмөлөрү". Oracle бул тема боюнча өзүнчө окуу куралы бар: Javadoc куралы үчүн Документке комментарийлерди кантип жазуу керек . IDEдеги кеңештер жакшы, бирок алар чындыгында кандайдыр бир себептерден улам documentтер. Бул JavaDoc комментарийлеринин негизинде documentтер түзүлөт. Бул үчүн атайын javadoc утorтасы бар . Көрүнүп тургандай, бул окуу куралы бул тууралуу айтылат. Аны кантип колдонуу керектигинин сүрөттөлүшү JavaDoc үчүн расмий Oracle веб-сайтында . Мунун кандай экенин өз көзүңүз менен көрүү үчүн, каталогдо пакеттин аталышы менен подкаталог түзө аласыз, мисалы: test . Андагы комментарийлер менен жөнөкөй класс түзүңүз. Мисалы:

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

Андан кийин, пакет каталогубузду камтыган каталогдон төмөнкү буйрукту иштете алабыз: javadoc -d ./test test Андан кийин биз documentтерди түзүү процессин көрөбүз. Андан кийин түзүлгөн documentти көрүү үчүн index.html ача алабыз. Сиз көп учурда API documentтеринин жайгаштырылып жатканын көрөсүз. Мисалы, Spring Framework API .

Корутунду

Көрүнүп тургандай, комментарийлер сыяктуу жөнөкөй көрүнгөн нерсе чындыгында алда канча татаал болуп чыгат. Ошондуктан, эгер сиз комментарийлерге бир аз убакыт бөлүп, аларды аткарсаңыз, codeуңуз жакшырып, программист катары баалуураак болосуз. #Вячеслав