Java-da rəy sətri (comment line), JavaDoc və boş sətir

Şərh, yaxud rəy olaraq yazılan yazılar Java tərtibçisi (kompayler – compiler) tərəfindən nəzərə alınmır. Yəni bu, compiler-in icra etmədiyi, önəmsəmədiyi hissədir ki, bunu özümüz yaxud kodumuzdan istifadə edəcək başqa insanlar üçün əlavə qeyd olaraq yazırıq. Burada istənilən şeyi istənilən şəkildə yaza bilərik, hətta yazı səhvi də olsa, xəta vermir, çünki compiler onu görməzdən gəlir. Java-da 2 fərqli formada rəy yazma şəkli var - təksətirli və çoxsətirli rəy:

1 .  // yəni qoşa əyri xətt ilə (end-of-line comment) - olduğu hissədən sətrin sonuna qədər olan hissəni tamamilə rəy sətri edir, həmin sətrdə ondan öncə yazılan hissə koda daxil hesab edilir, o işarədən sonra sətrin sonuna qədər olan hissə isə rəy sətri olur və koda aid sayılmır. Məs:

Burada yazılan - “//Burada 18 - a dəyişəninə mənimsədilir” - hissəsi kodun parçası sayılmır.

Bütöv bir sətri də rəy sətri etmək olar:

Buna “Comment out”, yəni rəy sətri etmək deyilir. “Uncomment out” isə o sətri rəy sətrindən çıxarmaq deməkdir. Hansısa bir sətri rəy səthi etmək üçün əl ilə o yazının öncəsinə // işarəsi qoya bilərik, həmçinin IDE-lərdə bunu ctrl+shift+c ilə yaxud ctrl+l qısayolları ilə də edə bilərik.

2. /*  */ - birdən çox sətri rəy sətri etmək üçün isə bu işarələri qoyub, yazıları bu iki işarənin, yəni /* və */ işarələri arasına əlavə edirik, bu zaman o hissəni rəy bloku edir (block/traditional comment). Məs:

Hətta ara sətirlərin başında * işarəsi olmasa da olar, əsas, /* və */ işarələrinin doğru yerlərdə olmasıdır. Həmçinin, alt-alta olan sətrləri hər sətir başına // işarələri qoyaraq da rəy sətri edə bilərik. Yəni yuxarıdakı yazı ilə bu yazı eynidir:

Bir sətrlik qeydi də eyni sətrdə /* və */ işarələri arasına yazmaq mümkündür:

Yuxarıdakı yazı ilə bu yazı eynidir:

Kodda rəy olaraq yazılan heç bir şey proqram icra olunan zaman işə düşmür, onların proqramın işinə aidiyyatı yoxdur.

Bu rəy özəllikləri ilə bağlı bəzi qaydalar var:

• Rəylər - həm sinfin içində, həm də çölündə ola bilər, yəni sinif blokunun içində də çölündə də rəylər yaza bilərik. Sinif adından üstdə, sinif adının altında, həmçinin, sinif blokunun içində yaxud kənarında yazılması mümkündür - yerinə uyğun istifadə edilir. Əgər bir metoda yaxud dəyişənə aid qeyd varsa, həmin rəyi adətən, onun üzərində yazırlar. Rəy ümumilikdə sinfə aiddirsə, adətən, sinif adının üzərində yazılır. Yəni aid olduğu şeydən adətən öncə yazılır.
• İfadə içində, yəni koda daxil olan hər hansı bir sətrin içində, kodun arasında // işarəsini yazmaq olmaz. Məs:

Bu şəkildə yaza bilmərik.

/* */ bu işarələri ifadə aralarına yaza bilərik, amma kodun oxunaqlığını azaldır və xoş olmayan bir görüntü yaradır.

• Amma mətnlərin arasına yazmaq olar. Məs:

Bu zaman bu // işarələrini də String mətninin bir parçası olaraq görüb, yazını o şəkildə, yəni içində // işarələri ilə də çap edəcək. String yaxud sabitlərin içində istifadə olunanda, o, rəy sətri kimi görünmür, elə mətnin içində işarə kimi də çap olunur.

• Rəy işarələri bir-birinin içində yazılmamalıdır. Birini yazdığımız yerdə digərini yazmağa gərək yoxdur. Məsələn, // yazdığımız sətrdə bir də /*  */ bunu yazmağın, həmçinin, /* … */ bu işarələrin arasına // bu işarələri yazmağın, həmçinin eyni yerdə bu işarələrdən hansısa birini təkrarən istifadə etməyin mənası yoxdur. Bunlardan birinin istifadəsi yetərlidir.

JavaDoc rəyləri

JavaDoc ilə dokumentasiya yaratmaq üçün /**  */ işarələrindən istifadə olunur. Normalda yuxarıda qeyd olunan 2 növdə rəy işarələrini qoyanda həmin sətrin rəngi zəifləyir, kölgəli şəkildə oxunur, amma bu işarələri qoyanda isə kodumuz kimi normal şəkildə görünür. Əsasən, API (Application Programming Interface) dokumentasiyası üçün istifadə edilir. Burada html kodları da yaza bilərik.

// və /* */ - bu ikisi kod içi dokumentasiya; JavaDoc /**  */ isə API dokumentasiyası üçün istifadə olunur və əasən, sinfin başında yazılır. Məs:

Dokumentasiyaya nə zaman ehtiyac var?

JavaDoc ilə yazılan API dokumentasiyasını çıxmaq şərtilə, kod içi dokumentasiya yerinə, daha aydın kod yazmaq lazımdır. Çünki hər dokumentasiya bir “üzr”-dür. Çünki yazılan kod anlaşılır olmalıdır, rəy əlavə etmək isə o kodun açıqlamaya ehtiyacı olduğunu bildirir. Bunun yerinə təmiz kod yazmaq lazımdır. Aydın şəkildə yazılmış kodun dokumentasiyaya az ehtiyacı olar. Olsa da, bu, API ilə bağlı ola bilər, məsələn, hansısa metodun işi haqda yaza bilərik və s. həqiqətən də vacib olan vəziyyətlərdə. Qarışıq kod yazıb, bir də onu açıqlamağa çalışmaq yerinə, daha oxunaqlı, təmiz kod yazmaq lazımdır.

Java-da boş sətir:

Yalnız ağ boşluqdan ibarət olan, heç nə yazılmayan, həmçinin, özündə hansısa şərhi saxlayan sətir boş sətir kimi tanınır və Java ona ümumiyyətlə məhəl qoymur.