Java-da sharhlar: hamma narsa juda oddiy emas

Kirish

Sharhlar - bu oddiyroq bo'lishi mumkindek tuyuladi va nima uchun butun maqola yozish kerak. Lekin bu unchalik oddiy emas. Rahbarim aytganidek, har kim kod yozishi mumkin, lekin yaxshi sharh yozish qiyin. Ko'pgina til kurslari an'anaviy Hello World bilan boshlanadi. Hatto Oracle Tutorials- ning "Ishga tushirish" bo'limida biz "Salom dunyo!" Ilova . Va kodning birinchi qatorlaridan biz ularni ko'ramiz - Java sharhlari. Ularning ahamiyati Java kodlari konventsiyasi kabi muhim hujjatda sharhlarga alohida bo'lim berilganligi bilan ham ta'kidlanadi: Sharhlar . Hujjatlarga ko'ra, Java-da sharhlar ikki turga bo'linadi:

• amalga oshirish sharhi (yoki kod sharhi);
• izohni hujjatlashtirish.

Kod sharhlari alohida satrlarni/bloklarni tavsiflash uchun ishlatiladi va hujjat sharhlari kodning spetsifikatsiyasini (uning interfeysi) amalga oshirilishidan qat'iy nazar tasvirlash uchun ishlatiladi. Java sharhlari kompilyator tomonidan e'tiborga olinmaydi, chunki ular foydalanuvchi uchun emas, balki ishlab chiquvchi uchun mantiqiydir. Shuning uchun siz kompilyatsiya qilingan sinflar hajmini kamaytirishingiz mumkin.

Java kodi sharhlari

Nomidan ko'rinib turibdiki, bu sharh kodga tegishli va uning xususiyatlarini aks ettirishi kerak. Kod sharhlari:

• Kichik harf (ya'ni, bitta qatorda tasvirlangan)

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




• Blok (ya'ni, ular butun blok sifatida tasvirlangan, chunki ular bir qatorga to'g'ri kelmaydi)

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

Blok izohining qiziqarli xususiyati shundan iboratki, agar biz uni “ /*- ” bilan boshlasak (ya’ni yulduzchadan keyin minus belgisi qo‘shsak), bu blok izohining matni formatlanmaydi. Qiziqarli, lekin ba'zi sharhlar yordamida siz IDE bo'yicha ba'zi maslahatlar berishingiz mumkin. Masalan, Eclipse IDE da " //@formatter:on " va " //@formatter:off " inline izohlaridan foydalanib, kod bo'limlari uchun formatlashni o'chirib qo'yishingiz mumkin. Sharhlarni tejamkorlik bilan va faqat kerak bo'lganda ishlatishingiz kerak. Masalan, siz ushbu mavzu bo'yicha maqolani o'qishingiz mumkin: "Kodga sharh yozmang!" . Robert Martinning " Toza kod: yaratish, tahlil qilish va qayta ishlash" nomli ajoyib kitobi bor . Unda "Izohlar" alohida bo'limi mavjud. Ushbu bobning epigrafi sifatida, xuddi shunday ajoyib iqtibos: Brayan V. Kernigan va P. J. Plowerdan "Yomon kodni izohlamang - uni qayta yozing". Ushbu bo'limni Google Kitoblarida topish mumkin . Umumiy ma'noni undan bitta iqtibos bilan ifodalash mumkin:

Har safar fikr bildirganingizda, irg'iling va o'zingizni muvaffaqiyatsizlikka uchragandek his eting."

Mutlaq haqiqat yo'qligi aniq va ba'zida sharhlar kerak. Lekin har doim variantlar mavjud va keraksiz sharhlar bilan kurashish kerak. Ushbu bobda g'ayrioddiy izohlar ham eslatib o'tilgan, TODO:

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

Ularning mohiyati shundaki, ular IDEda maxsus tarzda ishlov berilishi mumkin. Misol uchun, IDEA-da ular alohida yorliqda to'plangan, siz ularni ko'rishingiz mumkin: Va izohli kichik boshqotirma: “http://google.com” qatori usul ichida haqiqiy qatordir, chunki http bu yerda aslida teg, keyin esa izoh. Ko'pincha ko'plab sharhlar kod sharhlaridan hujjat sharhlariga o'tishi mumkin, biz bu haqda keyinroq gaplashamiz.

Hujjatlar uchun sharhlar

Hujjatlarga sharhlar umumiy APIni tavsiflaydi. API - bu amaliy dasturlash interfeysi, ya'ni boshqa ishlab chiquvchilar uchun har qanday harakatlarni bajarish uchun mavjud bo'lgan sinflar va usullar. Xulosa qilib aytganda, bu sharhlar nima uchun u yoki bu sinf va paket yaratilganligini va u yoki bu usul nima qilishini tushuntirishi kerak. Agar kerak bo'lsa, sinf maydonlarini ham tasvirlashingiz mumkin. Aynan shu narsani biz JavaDoc sifatida formatlangan IDE-larimizning ko'rsatmalarida ko'ramiz. Masalan: Agar biz ushbu usulga kirsak, bu matn qaerdan kelganini ko'rishimiz mumkin: Yana Java-kod konventsiyasiga qarang: JavaDoc-ni qanday qilib to'g'ri formatlash haqida Kod konventsiyasi . Ular sharhlarni blokirovka qilishga biroz o'xshaydi, lekin bitta yulduzcha o'rniga (Asteriks emas) ikkitasi ishlatiladi. Misol uchun JavaDoc yuqorida keltirilgan. Barcha imkoniyatlarni tavsiflashning ma'nosi yo'q, chunki bu haqda Oracle rasmiy hujjatlarida allaqachon yozilgan. Shuning uchun biz rasmiy JavaDoc hujjatlarining "Teg tavsiflari" bo'limida bizga kerak bo'lgan hamma narsani ko'rib chiqamiz. Oracle-da hatto ushbu mavzu bo'yicha alohida qo'llanma mavjud: Javadoc Tool uchun hujjat sharhlarini qanday yozish kerak . IDE-dagi maslahatlar yaxshi, lekin ular biron bir sababga ko'ra hujjatlardir. Ushbu JavaDoc sharhlari asosida hujjatlar yaratiladi. Buning uchun maxsus javadoc yordam dasturi mavjud . Ko'rib turganimizdek, o'quv qo'llanma bu haqda gapiradi. Uni qanday ishlatish tavsifi JavaDoc uchun rasmiy Oracle veb-saytida joylashgan . Bu qanday ko'rinishini o'zingiz ko'rish uchun katalogda paket nomi bilan kichik katalog yaratishingiz mumkin, masalan: test . Izohlar bilan oddiy sinf yarating. Masalan:

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

Shundan so'ng biz paketlar katalogimiz joylashgan katalogdan quyidagi buyruqni ishga tushirishimiz mumkin: javadoc -d ./test test Shundan so'ng biz hujjatlarni yaratish jarayonini ko'ramiz. Va keyin yaratilgan hujjatni ko'rish uchun index.html ni ochishimiz mumkin. Siz tez-tez API hujjatlari joylashtirilayotganini ko'rasiz. Masalan, Spring Framework API .

Xulosa

Ko'rib turganimizdek, sharhlar kabi oddiy ko'rinadigan narsa haqiqatda ancha murakkabroq bo'lib chiqadi. Shuning uchun, agar siz sharhlarga biroz vaqt ajratsangiz va ularga amal qilsangiz, kodingiz yaxshiroq bo'ladi va siz dasturchi sifatida qimmatroq bo'lasiz. #Viacheslav