Шарҳҳо дар Java: на ҳама чиз оддӣ аст

Муқаддима

Шарҳҳо - чунин ба назар мерасад, ки он метавонад соддатар бошад ва чаро як мақолаи пурра нависед. Аммо ин чандон оддӣ нест. Тавре сардорам гуфт, ҳар кас метавонад code нависад, аммо навиштани шарҳи хуб мушкил аст. Аксарияти курсҳои забонӣ аз анъанавии Hello World оғоз мешаванд. Ҳатто дар дастурҳои Oracle, дар бахши "Оғози кор" мо бо "Салом Ҷаҳон!" оғоз мекунем. Ариза . Ва аз сатрҳои аввали code мо онҳоро мебинем - шарҳҳои Java. Аҳамияти онҳо инчунин бо он таъкид карда мешавад, ки дар чунин як ҳуҷҷати муҳим ба монанди Конвенсияи Кодекси Java, шарҳҳо қисмати алоҳида дода шудаанд: Шарҳҳо . Тибқи ҳуҷҷатҳо, шарҳҳо дар Java ба ду намуд тақсим мешаванд:

• шарҳи татбиқ (ё шарҳи code);
• ҳуҷҷатгузории шарҳ.

Шарҳҳои codeҳо барои тавсифи сатр/блокҳои инфиродӣ ва шарҳҳои ҳуҷҷатгузорӣ барои тавсифи мушаххасоти code (интерфейси он) новобаста аз татбиқи он истифода мешаванд. Шарҳҳои Java аз ҷониби компилятор нодида гирифта мешаванд, зеро онҳо барои таҳиякунанда маъно доранд, на корбар. Аз ин рӯ, шумо метавонед андозаи синфҳои тартибдодашударо кам кунед.

Шарҳҳои рамзи Java

Аз ном маълум мешавад, ки ин шарҳ ба code дахл дорад ва бояд хусусиятҳои онро инъикос кунад. Шарҳҳои code инҳоянд:

• Ҳарфи хурд (яъне дар як сатр тасвир шудааст)

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




• Блок (яъне онҳо ҳамчун як блок тавсиф карда мешаванд, зеро онҳо дар як сатр мувофиқ нестанд)

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

Хусусияти ҷолиби шарҳи блок дар он аст, ки агар мо онро бо “ /*- ” оғоз кунем (яъне пас аз ситорача аломати минусро илова кунем), пас матни шарҳи блок формат карда намешавад. Ҷолиб, аммо бо ёрии шарҳҳои муайян шумо метавонед якчанд маслиҳатҳои IDE диҳед. Масалан, бо истифода аз шарҳҳои дохor " //@formatter:on " ва " //@formatter:off " дар Eclipse IDE шумо метавонед форматкунии қисмҳои codeро ғайрифаъол кунед. Шумо бояд шарҳҳоро кам ва танҳо дар ҳолатҳои зарурӣ истифода баред. Масалан, шумо метавонед мақолаеро дар ин мавзӯъ хонед: "Дар бораи code шарҳ нанависед!" . Китоби олие вуҷуд дорад, ки аз ҷониби Роберт Мартин ном дорад, ки Кодекси тоза: Эҷод, Таҳлил ва Рефакторинг . Он боби алохидаи «Тафсирхо» дорад. Ҳамчун эпиграф ба ин боб, иқтибос ба ҳамон андоза олиҷаноб: "Коди бадро шарҳ надиҳед - онро аз нав нависед" аз Брайан В. Керниган ва П. Ҷ. Плоуэр. Ин бобро дар Google Books пайдо кардан мумкин аст . Маънои умумиро метавон дар як иқтибос аз ӯ баён кард:

Ҳар дафъае, ки шумо шарҳ медиҳед, ғамгин шавед ва худро ноком ҳис кунед."

Маълум аст, ки ҳақиқати мутлақ вуҷуд надорад ва баъзан шарҳҳо лозиманд. Аммо ҳамеша вариантҳо мавҷуданд ва шарҳҳои нолозим бояд мубориза баранд. Дар ин боб инчунин шарҳҳои ғайриоддӣ зикр шудаанд, TODO:

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

Ҳадафи онҳо дар он аст, ки онҳо метавонанд дар IDE ба таври махсус коркард карда шаванд. Масалан, дар IDEA онҳо дар ҷадвали алоҳида ҷамъ карда мешаванд, ки дар он шумо метавонед онҳоро бубинед: Ва муаммои хурде бо шарҳ: Хати "http://google.com" хати дуруст дар дохor усул аст, зеро http дар ин ҷо воқеан тег ва сипас шарҳ аст. Аксар вақт шарҳҳои зиёде метавонанд аз шарҳҳои рамзӣ ба шарҳҳои ҳуҷҷатгузорӣ гузаранд, ки мо дар бораи онҳо баъдтар сӯҳбат хоҳем кард.

Шарҳҳо барои ҳуҷҷатгузорӣ

Шарҳҳои ҳуҷҷатгузорӣ API-и оммавиро тавсиф мекунанд. API интерфейси барномасозии барнома мебошад, яъне он синфҳо ва усулҳое, ки барои иҷрои ҳама гуна амалҳо барои таҳиягарони дигар дастрасанд. Хулоса, ин шарҳҳо бояд шарҳ диҳанд, ки чаро ин ё он синф ва бастаҳо офарида шудаанд ва ин ё он усул чӣ кор мекунад. Агар лозим бошад, шумо инчунин метавонед майдонҳои синфро тавсиф кунед. Ин маҳз ҳамон чизест, ки мо дар маслиҳатҳои асбобҳои IDE-и худ мебинем, ки ҳамчун JavaDoc пешниҳод карда мешавад. Барои намуна: Агар мо ба ин усул равем, мо мебинем, ки ин матн аз куҷост: Боз ба Конвенсияи Кодекси Java нигаред: Конвенсияи Кодекс дар бораи тарзи дуруст формат кардани JavaDoc . Онҳо то андозае ба блоки шарҳҳо монанданд, аммо ба ҷои як ситорача (на Астерикс) ду истифода мешаванд. Намунаи JavaDoc дар боло оварда шудааст. Тавсифи ҳамаи имкониятҳо маъное надорад, зеро ин аллакай дар ҳуҷҷатҳои расмии Oracle навишта шудааст. Аз ин рӯ, мо ҳама чизеро, ки ба мо лозим аст, дар ҳуҷҷатҳои расмии JavaDoc , бахши "Тасвирҳои барчаспҳо" дида мебароем . Oracle ҳатто дар ин мавзӯъ як дастури алоҳида дорад: Чӣ гуна бояд шарҳҳои ҳуҷҷатро барои абзори Javadoc нависед . Маслиҳатҳои асбобҳо дар IDE хубанд, аммо онҳо аслан бо як сабаб ҳуҷҷатанд. Дар асоси ин шарҳҳои JavaDoc, ҳуҷҷатҳо тавлид мешаванд. Барои ин як утorтаи махсуси javadoc мавҷуд аст . Тавре ки мо мебинем, ин дастур дар бораи ин сухан меравад. Тавсифи тарзи истифодаи он дар вебсайти расмии Oracle барои JavaDoc мавҷуд аст . Барои худ бубинед, ки ин чӣ гуна аст, шумо метавонед дар директория бо номи баста зеркаталог эҷод кунед, масалан: 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 Баъд аз ин мо раванди тавлиди ҳуҷҷатҳоро мебинем. Ва он гоҳ мо метавонем index.html -ро кушоем, то ҳуҷҷати тавлидшударо бубинем. Шумо аксар вақт мебинед, ки ҳуҷҷатҳои API интишор карда мешаванд. Масалан, API Spring Framework .

Хулоса

Тавре ки мо мебинем, чунин як чизи ба назар содда, ба монанди шарҳҳо дар воқеият хеле мураккабтар мегардад. Аз ин рӯ, агар шумо каме вақтро дар шарҳҳо сарф кунед ва онҳоро пайравӣ кунед, рамзи шумо беҳтар мешавад ва шумо ҳамчун як барномасоз арзишмандтар хоҳед шуд. #Вячеслав