جاوا میں تبصرے: سب کچھ اتنا آسان نہیں ہے۔

تعارف

تبصرے - ایسا لگتا ہے کہ یہ آسان ہوسکتا ہے، اور کیوں ایک مکمل مضمون لکھیں. لیکن یہ اتنا آسان نہیں ہے۔ جیسا کہ میرے باس نے کہا، کوئی بھی کوڈ لکھ سکتا ہے، لیکن اچھا تبصرہ لکھنا مشکل ہے۔ زیادہ تر زبان کے کورسز روایتی ہیلو ورلڈ سے شروع ہوتے ہیں۔ یہاں تک کہ اوریکل ٹیوٹوریلز میں ، "شروع کرنا" سیکشن میں، ہم "ہیلو ورلڈ!" کے ساتھ شروع کرتے ہیں۔ درخواست _ اور کوڈ کی پہلی لائنوں سے ہی ہم انہیں دیکھتے ہیں - جاوا تبصرے۔ ان کی اہمیت پر اس حقیقت سے بھی زور دیا گیا ہے کہ جاوا کوڈ کنونشن جیسی اہم دستاویز میں تبصروں کو ایک الگ سیکشن دیا گیا ہے: Comments ۔ دستاویزات کے مطابق، جاوا میں تبصروں کو دو اقسام میں تقسیم کیا گیا ہے:

• نفاذ کا تبصرہ (یا کوڈ تبصرہ)؛
• دستاویزی تبصرہ

کوڈ کے تبصرے انفرادی لائنوں/بلاکس کی وضاحت کے لیے استعمال کیے جاتے ہیں، اور دستاویزات کے تبصرے کوڈ (اس کے انٹرفیس) کی وضاحت کے لیے استعمال کیے جاتے ہیں جو اس کے نفاذ سے آزاد ہیں۔ جاوا تبصرے کو مرتب کرنے والے کے ذریعہ نظر انداز کیا جاتا ہے کیونکہ وہ ڈویلپر کو سمجھ میں آتے ہیں، صارف کو نہیں۔ لہذا، آپ مرتب شدہ کلاسوں کے سائز کو کم کر سکتے ہیں۔

جاوا کوڈ کے تبصرے

نام سے یہ واضح ہے کہ یہ تبصرہ کوڈ سے متعلق ہے اور اس کی خصوصیات کو ظاہر کرنا چاہئے۔ کوڈ کے تبصرے ہیں:

• لوئر کیس (یعنی ایک لائن میں بیان کیا گیا ہے)

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




• بلاک (یعنی انہیں ایک مکمل بلاک کے طور پر بیان کیا گیا ہے، کیونکہ وہ ایک لائن پر فٹ نہیں ہوتے ہیں)

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

بلاک کمنٹ کی ایک دلچسپ خصوصیت یہ ہے کہ اگر ہم اسے “ /*- ” سے شروع کریں (یعنی ستارے کے بعد مائنس کا نشان شامل کریں) تو اس بلاک کمنٹ کا متن فارمیٹ نہیں ہوگا۔ دلچسپ، لیکن کچھ کمنٹس کی مدد سے آپ کچھ IDE اشارے دے سکتے ہیں۔ مثال کے طور پر، Eclipse IDE میں ان لائن تبصرے " //@formatter:on " اور " //@formatter:off " کا استعمال کرتے ہوئے آپ کوڈ کے حصوں کے لیے فارمیٹنگ کو غیر فعال کر سکتے ہیں۔ آپ کو تبصروں کو تھوڑا اور صرف جہاں ضروری ہو استعمال کرنے کی ضرورت ہے۔ مثال کے طور پر، آپ اس موضوع پر ایک مضمون پڑھ سکتے ہیں: "کوڈ پر تبصرے نہ لکھیں!" . کلین کوڈ کے نام سے ایک عظیم کتاب ہے : رابرٹ مارٹن کی تخلیق، تجزیہ، اور ریفیکٹرنگ۔ اس کا ایک الگ باب "تبصرے" ہے۔ اس باب کے ایک ایپی گراف کے طور پر، برائن ڈبلیو کرنیگھن اور پی جے پلور کا ایک اتنا ہی عمدہ اقتباس: "خراب کوڈ پر تبصرہ نہ کریں—اسے دوبارہ لکھیں"۔ یہ باب Google Books پر پایا جا سکتا ہے ۔ عمومی مفہوم ان کے ایک اقتباس میں بیان کیا جا سکتا ہے:

ہر بار جب آپ تبصرہ کرتے ہیں، جھجکتے ہیں اور ناکامی کی طرح محسوس کرتے ہیں۔"

یہ واضح ہے کہ کوئی مطلق سچائی نہیں ہے، اور بعض اوقات تبصرے ضروری ہوتے ہیں۔ لیکن ہمیشہ آپشنز ہوتے ہیں، اور غیر ضروری تبصروں سے لڑنے کی ضرورت ہوتی ہے۔ اس باب میں غیر معمولی تبصروں کا بھی ذکر ہے، TODO:

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

ان کی بات یہ ہے کہ انہیں IDE میں ایک خاص طریقے سے ہینڈل کیا جا سکتا ہے۔ مثال کے طور پر، IDEA میں انہیں ایک علیحدہ ٹیب پر جمع کیا جاتا ہے، جہاں آپ انہیں دیکھ سکتے ہیں: اور ایک تبصرہ کے ساتھ ایک چھوٹا سا پزلر: لائن "http://google.com" طریقہ کے اندر ایک درست لائن ہے، کیونکہ http یہاں اصل میں ایک ٹیگ ہے، اور پھر ایک تبصرہ۔ اکثر بہت سے تبصرے کوڈ تبصروں سے دستاویزی تبصروں تک جا سکتے ہیں، جن کے بارے میں ہم بعد میں بات کریں گے۔

دستاویزات کے لیے تبصرے۔

دستاویزی تبصرے عوامی API کی وضاحت کرتے ہیں۔ API ایپلیکیشن پروگرامنگ انٹرفیس ہے، یعنی وہ کلاسز اور طریقے جو دوسرے ڈویلپرز کو کوئی بھی کارروائی کرنے کے لیے دستیاب ہیں۔ مختصراً، ان تبصروں میں یہ وضاحت کرنی چاہیے کہ یہ یا وہ کلاس اور پیکیج کیوں بنایا گیا اور یہ یا وہ طریقہ کیا کرتا ہے۔ اگر ضروری ہو تو آپ کلاس فیلڈز کی بھی وضاحت کر سکتے ہیں۔ یہ بالکل وہی ہے جو ہم اپنے IDEs کے ٹول ٹپس میں دیکھتے ہیں، جو جاوا ڈاک کے طور پر پیش کیا جاتا ہے۔ مثال کے طور پر: اگر ہم اس طریقہ پر جائیں تو ہم دیکھ سکتے ہیں کہ یہ متن کہاں سے آیا ہے: ایک بار پھر، جاوا کوڈ کنونشن: کوڈ کنونشن دیکھیں کہ JavaDoc کو صحیح طریقے سے فارمیٹ کرنے کا طریقہ ۔ وہ کسی حد تک بلاک تبصروں سے ملتے جلتے ہیں، لیکن ایک ستارے کے بجائے (Asterix) نہیں) دو استعمال کیے جاتے ہیں۔ JavaDoc کی ایک مثال اوپر دی گئی تھی۔ تمام امکانات کو بیان کرنے کا کوئی فائدہ نہیں ہے، کیونکہ یہ پہلے ہی سرکاری اوریکل دستاویزات میں لکھا جا چکا ہے۔ لہذا، ہم آپ کو آفیشل JavaDoc دستاویزات ، سیکشن "ٹیگ کی تفصیل" میں ہر چیز کو دیکھتے ہیں۔ اوریکل کے پاس اس موضوع پر ایک علیحدہ ٹیوٹوریل بھی ہے: Javadoc Tool کے لیے Doc Comments کیسے لکھیں ۔ IDE میں ٹول ٹِپس اچھی ہیں، لیکن وہ دراصل ایک وجہ سے دستاویزات ہیں۔ ان JavaDoc تبصروں کی بنیاد پر، دستاویزات تیار کی جاتی ہیں۔ اس کے لیے ایک خصوصی javadoc افادیت ہے ۔ جیسا کہ ہم دیکھ سکتے ہیں، وہ ٹیوٹوریل اس بارے میں بات کرتا ہے۔ اسے استعمال کرنے کے طریقے کی تفصیل JavaDoc کے لیے سرکاری Oracle ویب سائٹ پر موجود ہے ۔ یہ دیکھنے کے لیے کہ یہ کیسا لگتا ہے، آپ پیکیج کے نام کے ساتھ ڈائریکٹری میں ایک ذیلی ڈائرکٹری بنا سکتے ہیں، مثال کے طور پر: 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 دستاویزات کو پوسٹ ہوتے دیکھیں گے۔ مثال کے طور پر، Spring Framework API ۔

نتیجہ

جیسا کہ ہم دیکھ سکتے ہیں، تبصرے جیسی بظاہر سادہ سی چیز حقیقت میں بہت زیادہ پیچیدہ ہوتی ہے۔ لہذا، اگر آپ کمنٹس پر کچھ وقت صرف کرتے ہیں اور ان کی پیروی کرتے ہیں، تو آپ کا کوڈ بہتر ہوگا اور آپ ایک پروگرامر کے طور پر زیادہ قیمتی ہوں گے۔ #ویاچسلاو