Java тіліндегі түсініктемелер: бәрі қарапайым емес

Кіріспе

Түсініктемелер - бұл қарапайым болуы мүмкін сияқты көрінуі мүмкін және неге бүкіл мақаланы жазу керек. Бірақ бұл қарапайым емес. Бастығым айтқандай, кез келген адам code жаза алады, бірақ жақсы пікір жазу қиын. Көптеген тіл курстары дәстүрлі Сәлем әлемінен басталады. Тіпті Oracle оқулықтарында «Бастау» бөлімінде біз «Сәлем әлем!» деп бастаймыз. Қолдану . Ал codeтың алғашқы жолдарынан бастап біз оларды көреміз - Java түсініктемелері. Олардың маңыздылығы Java code конвенциясы сияқты маңызды құжатта түсініктемелерге жеке бөлім берілгенімен де атап өтіледі: Түсініктемелер . Құжаттамаға сәйкес Java тіліндегі түсініктемелер екі түрге бөлінеді:

• іске асыруға түсініктеме (немесе codeтық түсініктеме);
• түсініктемені құжаттау.

Кодтық түсініктемелер жеке жолдарды/блоктарды сипаттау үшін пайдаланылады, ал құжаттамалық түсініктемелер codeтың (оның интерфейсін) оның орындалуына тәуелсіз сипаттауды сипаттау үшін қолданылады. Java түсініктемелерін компилятор елемейді, себебі олар пайдаланушыға емес, әзірлеушіге мағына береді. Сондықтан құрастырылған сыныптардың көлемін азайтуға болады.

Java codeы түсініктемелері

Атауынан бұл түсініктеме codeқа қатысты екені және оның ерекшеліктерін көрсетуі керек екені анық. Кодтық түсініктемелер:

• Кіші әріп (яғни бір жолда сипатталған)

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




• Блок (яғни олар тұтас блок ретінде сипатталады, өйткені олар бір сызыққа сәйкес келмейді)

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

Блоктық түсініктеменің қызықты ерекшелігі, егер біз оны « /*- » арқылы бастасақ (яғни жұлдызшадан кейін минус белгісін қоссақ), онда бұл блоктық түсініктеменің мәтіні пішімделмейді. Қызықты, бірақ белгілі бір түсініктемелердің көмегімен сіз IDE кеңестерін бере аласыз. Мысалы, Eclipse IDE ішіндегі " //@formatter:on " және " //@formatter:off " кірістірілген түсініктемелерді пайдалану арқылы code бөлімдері үшін пішімдеуді өшіруге болады. Түсініктемелерді үнемді және қажет жерде ғана пайдалану керек. Мысалы, сіз осы тақырыптағы мақаланы оқи аласыз: «Кодқа түсініктеме жазбаңыз!» . Роберт Мартиннің «Таза code: жасау, талдау және рефакторинг» атты тамаша кітабы бар . Оның «Пікірлер» жеке тарауы бар. Осы тараудың эпиграфы ретінде бірдей тамаша дәйексөз: Брайан У. Керниган мен П. Дж. Плоуэрден: «Жаман codeқа түсініктеме бермеңіз, оны қайта жазыңыз». Бұл тарауды Google Books сайтынан табуға болады . Жалпы мағынаны оның бір дәйексөзімен көрсетуге болады:

Түсініктеме берген сайын, дірілдеп, сәтсіздікке ұшырағандай сезінесіз ».

Абсолютті шындықтың жоқтығы анық, кейде түсініктемелер қажет. Бірақ әрқашан нұсқалар бар, қажетсіз пікірлермен күресу керек. Бұл тарауда әдеттен тыс пікірлер де айтылады, TODO:

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

Олардың мәні - оларды IDE-де ерекше жолмен өңдеуге болады. Мысалы, IDEA бағдарламасында олар бөлек қойындыда жиналады, оларды көруге болады: Және түсініктемесі бар шағын басқатырғыш: «http://google.com» жолы әдіс ішіндегі жарамды жол болып табылады, өйткені http мұнда шын мәнінде тег, содан кейін түсініктеме. Көбінесе көптеген түсініктемелер codeтық түсініктемелерден құжаттық түсініктемелерге өтуі мүмкін, олар туралы кейінірек айтатын боламыз.

Құжаттамаға түсініктемелер

Құжаттаманың түсініктемелері жалпыға ортақ API сипаттайды. API - бұл қолданбалы бағдарламалау интерфейсі, яғни кез келген әрекеттерді орындау үшін басқа әзірлеушілерге қол жетімді сыныптар мен әдістер. Қысқаша айтқанда, бұл түсініктемелер осы немесе басқа класс пен буманың не үшін жасалғанын және бұл немесе басқа әдістің не істейтінін түсіндіруі керек. Қажет болса, сынып өрістерін де сипаттауға болады. JavaDoc ретінде пішімделген IDE құралдар кеңестерінде дәл осылай көреміз. Мысалы: Бұл әдіске кіретін болсақ, бұл мәтіннің қайдан шыққанын көре аламыз: JavaDoc файлын дұрыс пішімдеу жолы туралы Java codeы конвенциясы: code конвенциясын қайтадан қараңыз . Олар түсініктемелерді блоктауға ұқсас, бірақ бір жұлдызшаның орнына (Asterix емес) екеуі қолданылады. Жоғарыда JavaDoc мысалы келтірілген. Барлық мүмкіндіктерді сипаттаудың қажеті жоқ, өйткені бұл туралы ресми Oracle құжаттамасында жазылған. Сондықтан біз сізге қажет барлық нәрсені ресми JavaDoc құжаттамасында, «Tag сипаттамасы» бөлімінде қарастырамыз . Oracle-де бұл тақырып бойынша жеке оқу құралы бар: Javadoc құралы үшін құжатқа түсініктемелерді қалай жазу керек . IDE ішіндегі құралдар кеңестері жақсы, бірақ олар нақты себептермен құжаттар болып табылады. Осы JavaDoc түсініктемелерінің негізінде құжаттама жасалады. Бұл үшін арнайы 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 Осыдан кейін біз құжаттаманы құру процесін көреміз. Содан кейін жасалған құжатты көру үшін index.html ашуға болады. Сіз жиі API құжаттамасы жарияланып жатқанын көресіз. Мысалы, Spring Framework API .

Қорытынды

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