جاوا ۾ تبصرا: هر شيء ايترو سادو ناهي

تعارف

تبصرا - اهو لڳي ٿو ته اهو آسان ٿي سگهي ٿو، ۽ ڇو هڪ سڄو مضمون لکندو. پر اهو ايترو سادو ناهي. جيئن منهنجي باس چيو، ڪو به ڪوڊ لکي سگهي ٿو، پر سٺو تبصرو لکڻ ڏکيو آهي. اڪثر ٻولي جا ڪورس روايتي هيلو ورلڊ سان شروع ٿين ٿا. جيتوڻيڪ Oracle Tutorials ۾، "Getting Started" سيڪشن ۾، اسين شروع ڪريون ٿا The "Hello World!" درخواست . ۽ ڪوڊ جي پهرين لائنن مان اسان انهن کي ڏسون ٿا - جاوا تبصرا. انهن جي اهميت تي پڻ زور ڏنو ويو آهي حقيقت اها آهي ته جاوا ڪوڊ ڪنوينشن وانگر هڪ اهم دستاويز ۾، تبصرو هڪ الڳ سيڪشن ڏنو ويو آهي: تبصرا . دستاويزن موجب، جاوا ۾ تبصرا ٻن قسمن ۾ ورهايل آهن:

• عملدرآمد تبصرو (يا ڪوڊ تبصرو)؛
• دستاويزي تبصرو.

ڪوڊ تبصرا استعمال ڪيا ويندا آھن انفرادي لائنن/بلاڪن کي بيان ڪرڻ لاءِ، ۽ دستاويزن جا تبصرا استعمال ڪيا ويندا آھن بيان ڪرڻ لاءِ ڪوڊ جي وضاحت (ان جو انٽرفيس) ان جي عمل درآمد کان آزاد. جاوا تبصرا ڪمپلر طرفان نظرانداز ڪيا ويا آهن ڇاڪاڻ ته اھي سمجھندا آھن ڊولپر کي، نه صارف کي. تنهن ڪري، توهان مرتب ڪيل طبقن جي سائيز کي گهٽائي سگهو ٿا.

جاوا ڪوڊ تبصرا

نالي مان اهو واضح آهي ته هي تبصرو ڪوڊ سان لاڳاپيل آهي ۽ ان جي خاصيتن کي ظاهر ڪرڻ گهرجي. ڪوڊ تبصرا آهن:

• لوئر ڪيز (يعني هڪ لڪير ۾ بيان ڪيل)

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




• بلاڪ (يعني انهن کي مڪمل بلاڪ طور بيان ڪيو ويو آهي، ڇاڪاڻ ته اهي هڪ لڪير تي نه هوندا آهن)

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

بلاڪ تبصري جي هڪ دلچسپ خصوصيت اها آهي ته جيڪڏهن اسان ان کي شروع ڪريون ٿا “ /*- ” (يعني ستاري کان پوءِ مائنس جي نشاني شامل ڪريو) ته پوءِ هن بلاڪ تبصري جو متن فارميٽ نه ٿيندو. دلچسپ، پر ڪجهه راين جي مدد سان توهان ڪجهه IDE اشارا ڏئي سگهو ٿا. مثال طور، Eclipse IDE ۾ ان لائن تبصرا " //@formatter:on " ۽ " //@formatter:off " استعمال ڪندي توهان ڪوڊ جي حصن لاءِ فارميٽنگ کي غير فعال ڪري سگهو ٿا. توهان کي تبصرا استعمال ڪرڻ جي ضرورت آهي ٿوري ۽ صرف جتي ضروري هجي. مثال طور، توهان هن موضوع تي هڪ مضمون پڙهي سگهو ٿا: "ڪوڊ تي تبصرو نه لکو!" . هتي هڪ عظيم ڪتاب آهي جنهن کي صاف ڪوڊ سڏيو ويندو آهي: رابرٽ مارٽن پاران ٺاهي، تجزيو، ۽ ريفيڪٽرنگ. ان ۾ هڪ الڳ باب آهي ”تبصرا“. هن باب جي هڪ ايپيگراف جي طور تي، هڪ تمام سٺو اقتباس: "خراب ڪوڊ جو تبصرو نه ڪريو- ان کي ٻيهر لکو" Brian W. Kernighan ۽ P. J. Plower کان. هي باب گوگل بوڪس تي ڳولهي سگهجي ٿو . عام معنيٰ سندس هڪ اقتباس ۾ بيان ڪري سگهجي ٿي:

هر دفعي توهان تبصرو ڪيو، حيران ۽ ناڪامي وانگر محسوس ڪيو."

اهو واضح آهي ته ڪا به مڪمل سچائي نه آهي، ۽ ڪڏهن ڪڏهن تبصرو ضروري آهي. پر اتي هميشه اختيارن آهن، ۽ غير ضروري تبصرن سان جنگ ڪرڻ جي ضرورت آهي. هي باب پڻ غير معمولي تبصرن جو ذڪر ڪري ٿو، TODO:

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

انهن جو نقطو اهو آهي ته اهي IDE ۾ هڪ خاص طريقي سان هٿ ڪري سگهجن ٿيون. مثال طور، IDEA ۾ اهي هڪ الڳ ٽيب تي گڏ ڪيا ويا آهن، جتي توهان انهن کي ڏسي سگهو ٿا: ۽ هڪ ننڍڙو puzzler هڪ تبصرو سان: لڪير "http://google.com" طريقي جي اندر صحيح لائن آهي، ڇاڪاڻ ته http هتي اصل ۾ هڪ ٽيگ آهي، ۽ پوء هڪ تبصرو. گهڻو ڪري ڪيترائي تبصرا ٿي سگهن ٿا ڪوڊ تبصرن کان دستاويزي تبصرن تائين، جن بابت اسان بعد ۾ ڳالهائينداسين.

دستاويز لاء تبصرا

دستاويزي تبصرا عوامي API جي وضاحت ڪن ٿا. API هڪ ايپليڪيشن پروگرامنگ انٽرفيس آهي، يعني اهي طبقا ۽ طريقا جيڪي ٻين ڊولپرز وٽ موجود آهن ڪنهن به عمل کي انجام ڏيڻ لاءِ. مختصر ۾، انهن تبصرن کي وضاحت ڪرڻ گهرجي ته هي يا اهو طبقو ۽ پيڪيج ڇو ٺاهيو ويو ۽ اهو يا اهو طريقو ڇا ڪندو آهي. توھان پڻ بيان ڪري سگھو ٿا ڪلاس فيلڊز جيڪڏھن ضروري ھجي. اھو اھو آھي جيڪو اسان ڏسون ٿا اسان جي IDEs جي ٽول ٽائپس ۾، جيڪو پيش ڪيو ويو آھي JavaDoc طور. مثال طور: جيڪڏهن اسان هن طريقي ۾ وڃون ٿا، اسان ڏسي سگهون ٿا ته هي متن ڪٿان اچي ٿو: ٻيهر، ڏسو جاوا ڪوڊ ڪنوينشن: ڪوڊ ڪنوينشن تي ڪيئن صحيح طريقي سان فارميٽ ڪجي JavaDoc . اهي ڪجهه حد تائين بلاڪ تبصرن سان ملندڙ جلندڙ آهن، پر ان جي بدران هڪ اسٽرڪڪ (نه ايسٽرڪس)) ٻه استعمال ڪيا ويا آهن. ھڪڙو مثال JavaDoc مٿي ڏنل آھي. سڀني امڪانن کي بيان ڪرڻ ۾ ڪو به نقطو نه آهي، ڇاڪاڻ ته اهو اڳ ۾ ئي سرڪاري Oracle دستاويزن ۾ لکيو ويو آهي. تنهن ڪري، اسان هر شي کي ڏسو ٿا جيڪو توهان کي گهربل آهي سرڪاري JavaDoc دستاويزن ۾ ، سيڪشن "ٽيگ وضاحتون". Oracle وٽ پڻ هن موضوع تي هڪ الڳ سبق آهي: Javadoc Tool لاءِ Doc Comments ڪيئن لکجي . IDE ۾ ٽول ٽائپس سٺا آهن، پر اهي اصل ۾ هڪ سبب لاءِ دستاويز آهن. انهن JavaDoc تبصرن جي بنياد تي، دستاويز ٺاهي وئي آهي. ھن لاء ھڪڙو خاص جاواڊڪ افاديت آھي . جيئن اسان ڏسي سگهون ٿا، اهو سبق هن بابت ڳالهائيندو آهي. ان کي ڪيئن استعمال ڪجي جو تفصيل سرڪاري Oracle ويب سائيٽ تي JavaDoc لاءِ آهي . پاڻ کي ڏسڻ لاءِ ته هي ڇا ٿو لڳي، توهان ڊاريڪٽري ۾ هڪ ذيلي ڊائريڪٽري ٺاهي سگهو ٿا پيڪيج جي نالي سان، مثال طور: 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 دستاويز پوسٽ ڪئي پئي وڃي. مثال طور، اسپرنگ فريم ورڪ API .

نتيجو

جيئن ته اسان ڏسي سگهون ٿا، اهڙي بظاهر سادي شيء جيئن ته تبصرا حقيقت ۾ گهڻو وڌيڪ پيچيده ٿي ويندا آهن. تنهن ڪري، جيڪڏهن توهان تبصرن تي ڪجهه وقت گذاريو ۽ انهن جي پيروي ڪندا، توهان جو ڪوڊ بهتر ٿيندو ۽ توهان هڪ پروگرامر جي حيثيت ۾ وڌيڪ قيمتي هوندا. #وياچسلاو