Java-da şərhlər: hər şey o qədər də sadə deyil

Giriş

Şərhlər - görünür ki, daha sadə ola bilər və niyə bütöv bir məqalə yazmaq lazımdır. Amma bu o qədər də sadə deyil. Müdirimin dediyi kimi, hər kəs kod yaza bilər, amma yaxşı şərh yazmaq çətindir. Dil kurslarının əksəriyyəti ənənəvi Hello World ilə başlayır. Hətta Oracle Dərsliklərində, "Başlanğıc" bölməsində biz "Salam Dünya!" Tətbiq . Və kodun ilk sətirlərindən biz onları görürük - Java şərhləri. Onların əhəmiyyəti Java Kod Konvensiyası kimi mühüm sənəddə şərhlərə ayrıca bölmənin verilməsi ilə də vurğulanır: Şərhlər . Sənədlərə görə, Java-da şərhlər iki növə bölünür:

• icra şərhi (və ya kod şərhi);
• şərhin sənədləşdirilməsi.

Kod şərhləri fərdi sətirləri/blokları təsvir etmək üçün istifadə olunur və sənəd şərhləri kodun spesifikasiyasını (onun interfeysini) onun həyata keçirilməsindən asılı olmayaraq təsvir etmək üçün istifadə olunur. Java şərhləri tərtibçi tərəfindən nəzərə alınmır, çünki onlar istifadəçi üçün deyil, tərtibatçı üçün məna kəsb edir. Buna görə tərtib edilmiş siniflərin ölçüsünü azalda bilərsiniz.

Java kodu şərhləri

Adından aydın olur ki, bu şərh koda aiddir və onun xüsusiyyətlərini əks etdirməlidir. Kod şərhləri bunlardır:

• Kiçik hərf (yəni bir sətirdə təsvir olunur)

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




• Blok (yəni onlar bütöv blok kimi təsvir olunur, çünki onlar bir xəttə sığmır)

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

Blok şərhinin maraqlı xüsusiyyəti ondan ibarətdir ki, onu “ /*- ” ilə başlasaq (yəni ulduzdan sonra mənfi işarə əlavə etsək), bu blok şərhinin mətni formatlanmayacaq. Maraqlıdır, lakin müəyyən şərhlərin köməyi ilə bəzi IDE göstərişləri verə bilərsiniz. Məsələn, Eclipse IDE-də " //@formatter:on " və " //@formatter:off " daxili şərhlərdən istifadə edərək, kod bölmələri üçün formatlaşdırmanı söndürə bilərsiniz. Şərhlərdən az istifadə etməlisiniz və yalnız lazım olduqda. Məsələn, bu mövzuda bir məqalə oxuya bilərsiniz: "Koda şərh yazmayın!" . Robert Martinin Təmiz Kod: Yaratmaq, Təhlil və Refaktorinq adlı gözəl kitabı var . Onun ayrıca “Şərhlər” bölməsi var. Bu fəslin epiqrafı kimi, eyni dərəcədə əla sitat: "Pis kodu şərh etməyin - onu yenidən yazın" Brian W. Kernighan və P. J. Plower. Bu fəsil Google Kitablarda tapıla bilər . Ümumi məna ondan bir sitatla ifadə edilə bilər:

Hər dəfə şərh yazdığınız zaman üzünüzü çəkin və uğursuzluq hiss edin."

Aydındır ki, mütləq həqiqət yoxdur, bəzən şərhlər də lazım olur. Ancaq həmişə variantlar var və lazımsız şərhlərlə mübarizə aparmaq lazımdır. Bu fəsildə qeyri-adi şərhlər də qeyd olunur, TODO:

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

Onların məqsədi IDE-də xüsusi bir şəkildə idarə oluna bilməsidir. Məsələn, IDEA-da onlar ayrıca tabda toplanır, burada onlara baxa bilərsiniz: Və şərhi olan kiçik bir tapmaca: “http://google.com” xətti metod daxilində etibarlı bir xəttdir, çünki http burada əslində bir etiketdir, sonra isə şərhdir. Çox vaxt bir çox şərhlər kod şərhlərindən sənəd şərhlərinə qədər gedə bilər, bu barədə daha sonra danışacağıq.

Sənədlər üçün şərhlər

Sənəd şərhləri ictimai API-ni təsvir edir. API tətbiq proqramlaşdırma interfeysidir, yəni hər hansı bir hərəkəti yerinə yetirmək üçün digər tərtibatçılar üçün mövcud olan siniflər və üsullardır. Bir sözlə, bu şərhlər bu və ya digər sinif və paketin nə üçün yaradıldığını və bu və ya digər metodun nə etdiyini izah etməlidir. Lazım gələrsə, sinif sahələrini də təsvir edə bilərsiniz. JavaDoc kimi təqdim olunan IDE-lərimizin göstərişlərində məhz bunu gördük. Misal üçün: Bu üsula girsək, bu mətnin haradan gəldiyini görə bilərik: Yenə də Java Kod Konvensiyasına baxın: JavaDoc-u düzgün formatlaşdırmaq üçün Kod Konvensiyası . Onlar şərhləri bloklamağa bir qədər bənzəyir, lakin bir ulduz əvəzinə (Asteriks deyil) ikisi istifadə olunur. JavaDoc nümunəsi yuxarıda verilmişdir. Bütün imkanları təsvir etməyin mənası yoxdur, çünki bu barədə rəsmi Oracle sənədlərində artıq yazılıb. Buna görə də, biz lazım olan hər şeyi rəsmi JavaDoc sənədlərində , "Etiket təsvirləri" bölməsində nəzərdən keçiririk. Oracle-ın hətta bu mövzuda ayrıca təlimatı var: Javadoc Aləti üçün Sənəd Şərhlərini Necə Yazmaq olar . IDE-də göstərişlər gözəldir, lakin onlar əslində bir səbəbə görə sənədlərdir. Bu JavaDoc şərhləri əsasında sənədlər yaradılır. Bunun üçün xüsusi javadoc yardım proqramı var . Gördüyümüz kimi, Dərslik bu barədə danışır. Onun necə istifadə ediləcəyi təsviri JavaDoc üçün rəsmi Oracle veb-saytındadır . Bunun necə göründüyünü özünüz görmək üçün kataloqda paketin adı ilə bir alt kataloq yarada bilərsiniz, məsələn: test . Şərhlərlə sadə bir sinif yaradın. Misal üçün:

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

Bundan sonra, paket qovluğumuzu ehtiva edən qovluqdan aşağıdakı əmri işlədə bilərik: javadoc -d ./test test Bundan sonra biz sənədlərin yaradılması prosesini görəcəyik. Və sonra yaradılan sənədi görmək üçün index.html aça bilərik. Tez-tez API sənədlərinin yerləşdirildiyini görəcəksiniz. Məsələn, Spring Framework API .

Nəticə

Gördüyümüz kimi, şərhlər kimi sadə görünən bir şey reallıqda daha mürəkkəbdir. Odur ki, şərhlərə bir az vaxt ayırıb onları izləsəniz, kodunuz daha yaxşı olacaq və bir proqramçı kimi daha dəyərli olacaqsınız. #Viaçeslav