جاوا تبصرا

تبصرا هڪ پروگرام جو حصو آهن جن تي عمل نه ڪيو ويو آهي. مرتب ڪندڙ صرف تبصرن کي نظر انداز ڪري ٿو ڇاڪاڻ ته اهي ان لاءِ نه آهن. اهي ”انساني“ ٻوليءَ ۾ لکيل آهن ۽ انهن جو مقصد پروگرام جي وضاحت ڪرڻ آهي، پروگرام جو حصو، ڊولپرز يا ترقي ۾ شامل ماڻهن لاءِ هڪ واحد لڪير يا طريقو. گهڻو ڪري، تبصرا انگريزيء ۾ لکيل آهن، اهو هڪ قسم جو رواج آهي. هن آرٽيڪل ۾، اسان جاوا ۾ تبصرن بابت ڳالهائڻ وارا آهيون ۽ توهان ۽ توهان جي ٽيم جي ساٿين جي زندگي کي آسان ڪرڻ لاء انهن کي صحيح طريقي سان ڪيئن استعمال ڪجي.

جاوا تبصرا: ڇو اهي اهم آهن

انهن جو چوڻ آهي ته پروگرامر ڏاڍا سست هوندا آهن جڏهن اهو اچي ٿو انهن جي پنهنجي ڪوڊ تي تبصرو ڪرڻ. بهرحال، هي هڪ تمام اهم مهارت آهي، تنهنڪري ان کي گهٽ نه سمجهيو، جيتوڻيڪ توهان صرف جاوا سکڻ شروع ڪري رهيا آهيو. سٺو تبصرو ڪوڊ ڪوڊ کان وڌيڪ قيمتي آهي بغير تبصرن جي ڇو ته اهڙي پروگرام کي برقرار رکڻ تمام آسان آهي. جيئن ته وڏا منصوبا اڪثر جاوا ۾ لکيل آهن، قابل تبصرو پڻ ترقي کي تيز ڪري ٿو، ڇاڪاڻ ته اهو پروگرامر لاء ٻين ماڻهن جي ڪوڊ سان معاملو ڪرڻ آسان آهي. تبصرو ڪرڻ جي ضرورت آهي:

• ڪوڊ سمجھو. توهان جي يا ڪنهن ٻئي جي. جيڪڏهن توهان کي لڳي ٿو ته توهان کي پنهنجو ڪوڊ سمجهڻ جي ضرورت ناهي ڇو ته توهان اهو لکيو آهي، هڪ نسبتا پيچيده پروگرام کولڻ جي ڪوشش ڪريو جيڪو توهان هڪ مهينو اڳ يا ان کان به اڳ لکيو هو ۽ جلدي سمجھو ته ڇا، ڪٿي ۽ ڇو توهان جي ذهن ۾ هئي. تبصرا استعمال ڪري سگھجن ٿا پروگرام جي منطق کي بيان ڪرڻ لاءِ يا ڪنهن پروگرام جي بلاڪ سان گڏو گڏ انهن لاءِ سفارشون ڇڏي ڏيو جيڪي بعد ۾ توهان جي ڪوڊ سان ڪم ڪندا. هن قسم جي تبصري کي وضاحتي چئي سگهجي ٿو.

• شين جي مقصد جي باري ۾ معلومات تي مشتمل، ان پٽ ۽ آئوٽ پيٽرز (جيڪڏهن ڪو به هجي)، ڊولپر بابت ڊيٽا، ۽ ڪوڊ جي ٽڪڙي سان لاڳاپيل ٻيون اهم شيون. اهڙا تبصرا ماڊلز، لائبريرين، طريقيڪار، ۽ افعال جي هيڊرز ۾ موجود آهن. انهن کي دستاويزي تبصرو چئي سگهجي ٿو.

• بگ ڪنٽرول ڪريو ۽ ڪوڊ بهتر ڪريو. قابل اعتراض ڪوڊ يا ڪوڊ جيڪو سڌارڻ جي ضرورت آهي هميشه تبصرو ڪري سگهجي ٿو ۽ بعد ۾ نظرثاني ڪري سگهجي ٿو. جيڪڏهن توهان کي محسوس ٿئي ٿو ته هڪ خاص مسئلو مختلف طريقي سان حل ٿي سگهي ٿو، پر هاڻي توهان وٽ ان لاءِ وقت ناهي، هن خيال کي تبصري ۾ لکو. ٻي صورت ۾، گهڻو ڪري، نئين ڪوڊ جي دٻاء هيٺ، توهان ان جي باري ۾ وساريندا.

جاوا ۾ تبصرن جا قسم

ان حقيقت جي باوجود ته توهان تبصرن ۾ ڪجهه به ۽ سڀ ڪجهه لکي سگهو ٿا، جاوا ۾ ڪجهه قسم جا تبصرا آهن ۽ انهن کي استعمال ڪرڻ جا ضابطا. جاوا تبصرن ۾ ٿڌي ٿي:

• سنگل لائن تبصرا
• ملٽي لائن تبصرا
• دستاويزي تبصرا

سنگل لائن تبصرا

جاوا جا سڀ کان وڌيڪ عام تبصرا واحد لائن تبصرا آهن. اهڙي تبصري کي ظاهر ڪرڻ لاء، اهو ڪافي آهي ته متن جي اڳيان ٻٽي سليش رکڻ // . سنگل لائين تبصرا صرف تبصري جي شروعات ۾ نشان لڳل آهن. تبصرو لائن جي آخر تائين جاري آهي. نحو:

//here is a single line comment.

اچو ته هن قسم جا جاوا تبصرن جو هڪ مثال وٺون:

public class CommentsDemo1 {
   public static void main(String[] args) {
       System.out.println("This text is visible for Java compiler");
       //this text is single line comment
//This one is also single line comment
//they both (and me) are invisible for compiler
   }
}

پيداوار آهي: عام طور تي هڪ واحد لڪير تبصرو پروگرام ۾ تبصري واري جڳهه جي مٿان يا هيٺ واقع هوندو آهي، ڪڏهن ڪڏهن ساڳئي لائن تي. اهو ضروري آهي ته اهو واضح طور تي واضح هجي ته تبصرو ڇا ڏانهن اشارو ڪري ٿو.

ملٽي لائن تبصرا

ڪڏهن ڪڏهن جاوا تبصرو لکڻ لاءِ هڪ لائن ڪافي ناهي. مثال طور، توهان کي بيان ڪرڻ جي ضرورت آهي ته هڪ طريقو ڪيئن ڪم ڪري ٿو يا هڪ پيچيده فارمولا جيڪو توهان لاڳو ڪري رهيا آهيو. انهي حالت ۾، توهان لکي سگهو ٿا ڪيترن ئي واحد-لائن جا رايا، پر اهو وڌيڪ منطقي هوندو ته نام نهاد ملٽي لائين رايا لکڻ. انهن ٻنهي پاسن تي نشان لڳل آهن /* */ . گھڻن لائين تبصرن جو نحو:

/*This comment
is
Multi line comment
we can describe here
what we need */

اچو ته ڪوڊ ۾ ملٽي لائن تبصرن جو هڪ مثال ڏيو

public class RleTest {

   /*
   Run Length Encoding (RLE),  a data compression algorithm
   that replaces repeated characters (series)
   with one character and the number of its repetitions.

   this method is to decode a String using run-length encoding

    */
   private static String decodeRle(String encoded) {
       if (encoded.isBlank()) return "";
       StringBuilder result = new StringBuilder();
       int count = 0;
       char baseChar = encoded.charAt(0);
       for (int i = 1; i <= encoded.length(); i++) {
           char c = i == encoded.length() ? '$' : encoded.charAt(i);
           if (Character.isDigit(c)) {
               count = count * 10 + Character.digit(c, 10);
           } else {
               do {
                   result.append(baseChar);
                   count--;
               } while (count > 0);
               count = 0;
               baseChar = c;
           }
       }
       return result.toString();
   }
   public static void main(String[] args) {
       System.out.println(decodeRle("C3ecddf8"));
   }
}

جاوا دستاويزي تبصرا

هي هڪ خاص قسم جا جاوا تبصرا آهن جيڪي هڪ دستاويزي صفحو ٺاهڻ لاءِ استعمال ڪيا ويندا آهن. عام طور تي ڊولپر جاواڊڪ استعمال ڪندي دستاويزي تبصرا لکندا آهن، جاوا سورس ڪوڊ مان HTML فارميٽ ۾ API دستاويز ٺاهڻ لاءِ هڪ دستاويزي جنريٽر. جاواڊڪ پاران استعمال ڪيل دستاويزن جو فارميٽ جاوا طبقن کي دستاويز ڪرڻ لاءِ انڊسٽري معيار آهي ۽ سڀ کان وڌيڪ مشهور IDEs جهڙوڪ IntelliJ IDEA ۽ Eclipse، خودڪار طور تي Javadoc HTML ٺاهي ٿو. جاوا دستاويزي تبصرا هيٺ ڏنل نحو آهن:

/**
Some important Javadoc comments here
You don’t know it yet, but Javadoc rulez

@author  Java Developer
*/

هتي هڪ مثال آهي: اهو جاوا شارٽ ڪلاس جو هڪ ٽڪرو آهي. رستي ۾، توهان پنهنجي IDE مان ڪنهن به جاوا ڪلاس ڪوڊ کي ڏسي سگهو ٿا (مثال طور ونڊوز مان IntelliJ IDEA ۾ صرف دٻايو ctrl+LBM يا ctrl + b (ونڊوز ۾) ڪنهن به طبقي يا طريقي جي نالي تي).

package java.lang;

import jdk.internal.HotSpotIntrinsicCandidate;
import jdk.internal.misc.VM;

/**
* The {@code Short} class wraps a value of primitive type {@code
* short} in an object.  An object of type {@code Short} contains a
* single field whose type is {@code short}.
*
* <p>In addition, this class provides several methods for converting
* a {@code short} to a {@code String} and a {@code String} to a
* {@code short}, as well as other constants and methods useful when
* dealing with a {@code short}.
*
* @author  Nakul Saraiya
* @author  Joseph D. Darcy
* @see     java.lang.Number
* @since   1.1
*/
public final class Short extends Number implements Comparable<Short> {

   /**
    * A constant holding the minimum value a {@code short} can
    * have, -2<sup>15</sup>.
    */
   public static final short   MIN_VALUE = -32768;

   /**
    * A constant holding the maximum value a {@code short} can
    * have, 2<sup>15</sup>-1.
    */
   public static final short   MAX_VALUE = 32767;

   /**
    * The {@code Class} instance representing the primitive type
    * {@code short}.
    */
   @SuppressWarnings("unchecked")

ھتي آھي جاوا ڪوڊ جو ڄاتل سڃاتل ۽ پيار ڪندڙ مڙني نون بيز println() طريقي سان اھڙي راءِ سان:

/**
* Prints a String and then terminate the line.  This method behaves as
* though it invokes {@link #print(String)} and then
* {@link #println()}.
*
* @param x  The {@code String} to be printed.
*/
public void println(String x) {
   if (getClass() == PrintStream.class) {
       writeln(String.valueOf(x));
   } else {
       synchronized (this) {
           print(x);
           newLine();
       }
   }
}

Javadoc وٽ ڪجھ خاص Javadoc ٽيگ آھن جن کي @ سان نشان لڳايو ويو آھي توھان مٿي ڏنل ڪوڊ ۾ ڏسي سگھو ٿا. اهڙي Javadoc ٽيگ جو مثال @author آهي جيڪو ڪلاس ليکڪ جو نالو شامل ڪري ٿو. هڪ ٻيو Javadoc ٽيگ آهي @ جتان اهو هڪ تبصرو شامل ڪري ٿو جيڪو ظاهر ڪري ٿو ته هي طبقو استعمال ڪيو ويو آهي جاوا جي مخصوص ورزن کان. سٺو جاواڊڪ دستاويز لکڻ لاءِ علم ۽ تجربي جي ضرورت آهي (۽ صبر!). توهان Javadoc تي وڌيڪ معلومات حاصل ڪري سگهو ٿا سرڪاري دستاويز ۾ Javadoc Tool لاءِ Doc Comments ڪيئن لکجي .

PS حقيقي زندگي مان ڪجهه عجيب تبصرا مثال

/**
*Dear Maintainer
*
*Once you are done trying to 'optimize' this routine,
*and you have realized what a terrible mistake that was,
*please increment the following counter as a warning
*to the next guy.
*
*total_hours_wasted_here = 73
*/

Exception up = new Exception("Something is really wrong.");
throw up;  //ha ha

// When I wrote this, only God and I understood what I was doing
// Now, God only knows

// sometimes I believe compiler ignores all my comments

/**
Always returns true.
*/
public boolean isAvailable() {
return false;
}

جيڪو توهان سکيو ان کي مضبوط ڪرڻ لاءِ، اسان توهان کي اسان جي جاوا ڪورس مان هڪ وڊيو سبق ڏسڻ جي صلاح ڏيون ٿا