کوڈنگ کے اصول: درست ناموں کی طاقت، اچھے اور برے تبصرے۔

آپ کو کتنی بار کسی اور کے کوڈ کو کھودنا پڑا ہے؟ دو گھنٹے کے بجائے، آپ دو دن صرف کر سکتے ہیں تاکہ یہ سمجھ سکیں کہ کیا ہو رہا ہے۔ مزے کی بات یہ ہے کہ کوڈ لکھنے والے کے لیے سب کچھ صاف اور مکمل شفاف ہے۔ یہ حیرت کی بات نہیں ہے: سب کے بعد، کامل کوڈ ایک بہت ہی مبہم تصور ہے، کیونکہ ہر ڈویلپر کا دنیا اور کوڈ کا بھی اپنا نظریہ ہوتا ہے۔ میں ایک سے زیادہ بار ایسی صورتحال میں رہا ہوں جب ایک ساتھی کارکن اور میں نے ایک ہی کوڈ کو دیکھا اور اس کی درستگی اور صفائی کے بارے میں مختلف رائے رکھتے تھے۔ واقف لگتا ہے، ہے نا؟ پھر بھی، کچھ وقتی آزمائشی اصول ہیں جن پر عمل کرنا چاہیے۔ آخر میں، وہ آپ کے لئے فائدہ مند ہوں گے، کیونکہ اگر آپ اپنے کوڈ کو اس حالت میں چھوڑ دیتے ہیں جس میں آپ خود اسے حاصل کرنا چاہتے ہیں، تو دنیا تھوڑی زیادہ خوش اور صاف ہو جائے گی۔ کوڈنگ کے قواعد کے بارے میں ہمارے پچھلے مضمون (یا اس کے بجائے، چھوٹی گائیڈ) میں، ہمیں مجموعی طور پر ایک سسٹم اور اس کے اجزاء، جیسے آبجیکٹ، انٹرفیس، کلاسز، طریقے، اور متغیرات لکھنے کے لیے سفارشات کا تھوڑا سا احساس ملا۔ اسی مضمون میں، میں نے اتفاق سے بعض عناصر کے درست ناموں کا ذکر کیا۔ میں آج اس کے بارے میں بات کرنا چاہوں گا، کیونکہ درست نام کوڈ کو پڑھنے میں کئی گنا آسان بنا دیتے ہیں۔ ہم صحیح کوڈ کے موضوع کو کچھ عکاسیوں، کوڈ میں تبصروں کی چھوٹی مثالوں، اور اس بات پر غور کریں گے کہ آیا یہ اچھا ہے یا اتنا اچھا نہیں۔ ٹھیک ہے، چلو شروع کرتے ہیں۔

درست نام

درست نام کوڈ کی پڑھنے کی اہلیت کو بہتر بناتے ہیں، اس طرح اپنے آپ کو کوڈ سے واقف کرنے کے لیے درکار وقت کو کم کرتے ہیں، کیونکہ کسی طریقہ کا استعمال اس وقت بہت آسان ہوتا ہے جب اس کا نام اس کی فعالیت کو تقریباً بیان کرتا ہو۔ کوڈ میں موجود ہر چیز ناموں (متغیرات، طریقے، کلاسز، اشیاء، فائلز وغیرہ) پر مشتمل ہوتی ہے، اس لیے درست، صاف کوڈ بناتے وقت یہ نکتہ بہت اہم ہو جاتا ہے۔ اوپر کی بنیاد پر، نام کا مطلب ہونا چاہیے، مثال کے طور پر، متغیر کیوں موجود ہے، یہ کیا کرتا ہے، اور اسے کیسے استعمال کیا جاتا ہے۔ میں ایک سے زیادہ بار نوٹ کروں گا کہ متغیر کے لیے بہترین تبصرہ اسے اچھا نام دینا ہے۔

ٹی وی سیریز "شرلاک" سے (2010-2017)

نام دینے والے انٹرفیس

انٹرفیس میں عام طور پر ایسے نام ہوتے ہیں جو بڑے حرف سے شروع ہوتے ہیں اور CamelCase میں لکھے جاتے ہیں۔ انٹرفیس لکھتے وقت، اسے انٹرفیس (مثال کے طور پر، IUserService) کے طور پر نامزد کرنے کے لیے سابقہ ​​"I" کا اضافہ کرنا اچھا عمل سمجھا جاتا تھا، لیکن یہ کافی بدصورت اور پریشان کن لگتا ہے۔ ایسی صورتوں میں، بہتر ہے کہ سابقہ ​​(UserService) کو چھوڑ دیا جائے اور اس کے نفاذ کے نام کے ساتھ "Impl" کو بطور لاحقہ شامل کیا جائے (جیسے UserServiceImpl)۔ یا ممکنہ طور پر، آخری حربے کے طور پر، نفاذ کے نام میں ایک "C" سابقہ ​​شامل کریں (جیسے CUserService)۔

کلاس کے نام

بالکل انٹرفیس کی طرح، کلاس کے نام بڑے بنائے جاتے ہیں اور CamelCase استعمال کرتے ہیں۔ اس سے کوئی فرق نہیں پڑتا کہ ہم زومبی apocalypse کا سامنا کر رہے ہیں، اس سے کوئی فرق نہیں پڑتا ہے کہ اگر اختتام قریب ہے — کبھی نہیں، کبھی نہیں، کبھی بھی کلاس کا نام فعل نہیں ہونا چاہیے! کلاس اور آبجیکٹ کے نام اسم یا مرکب اسم (UserController، User Details، UserAccount، وغیرہ) ہونے چاہئیں۔ آپ کو ہر کلاس کے نام کے آخر میں ایپلی کیشن کا مخفف نہیں لگانا چاہیے، کیونکہ اس سے صرف غیر ضروری پیچیدگی پیدا ہوگی۔ مثال کے طور پر، اگر ہمارے پاس یوزر ڈیٹا مائیگریشن ایپلی کیشن ہے، تو براہ کرم ہر کلاس میں "UDM" شامل نہ کریں، یعنی UDMUserDetails، UDMUserAccount، UDMUserController۔

طریقوں کے نام

عام طور پر، طریقہ کار کے نام چھوٹے حروف سے شروع ہوتے ہیں، لیکن وہ اونٹ کیس اسٹائل (اونٹ کیس) بھی استعمال کرتے ہیں۔ اوپر، ہم نے کہا کہ کلاس کے نام کبھی بھی فعل نہیں ہونے چاہئیں۔ یہاں صورتحال بالکل برعکس ہے: طریقوں کے نام فعل یا فعل کے جملے ہونے چاہئیں: findUserById، findAllUsers، createUser وغیرہ۔ جب کوئی طریقہ (ساتھ ہی متغیرات اور کلاسز) بناتے ہیں، تو الجھن سے بچنے کے لیے ایک مستقل نام دینے کا کنونشن استعمال کریں۔ مثال کے طور پر، کسی صارف کو تلاش کرنے کے لیے، ایک طریقہ کو getUserById یا findUserById کا نام دیا جا سکتا ہے۔ اور ایک بات: طریقوں کے ناموں میں مزاح کا استعمال نہ کریں، کیونکہ ہو سکتا ہے کہ دوسرے لوگ مذاق نہ سمجھیں۔ نتیجے کے طور پر، وہ یہ سمجھنے میں ناکام ہو سکتے ہیں کہ طریقہ کیا کرتا ہے۔

متغیر نام

زیادہ تر معاملات میں، متغیر کے نام چھوٹے حروف سے شروع ہوتے ہیں اور CamelCase بھی استعمال کرتے ہیں، سوائے اس کے کہ جب متغیر عالمی مستقل ہو۔ ایسی صورتوں میں، نام کے تمام حروف بڑے حروف میں لکھے جاتے ہیں اور الفاظ کو انڈر سکور ("_") سے الگ کیا جاتا ہے۔ سہولت کے لیے، آپ متغیرات کو نام دیتے وقت بامعنی سیاق و سباق استعمال کر سکتے ہیں۔ دوسرے الفاظ میں، جب کوئی متغیر کسی بڑی چیز کے حصے کے طور پر موجود ہو، مثال کے طور پر، firstName، lastName، یا status۔ ایسی صورتوں میں، آپ ایک سابقہ ​​شامل کر سکتے ہیں جو اس چیز کی نشاندہی کرتا ہے جس سے یہ متغیر تعلق رکھتا ہے۔ مثال کے طور پر: userFirstName، userLastName، user Status۔ آپ کو متغیرات کے لیے ملتے جلتے ناموں سے بھی گریز کرنا چاہیے جب ان کے معنی بالکل مختلف ہوں۔ متغیر ناموں میں استعمال ہونے والے متضاد الفاظ یہ ہیں:

• شروع/ختم
• پہلا آخری
• مقفل/غیر مقفل
• کم از کم/زیادہ سے زیادہ
• اگلا/پچھلا
• پرانا/نیا
• کھلا/بند
• مرئی/غیر مرئی
• ذریعہ/ہدف
• ذریعہ/منزل
• اوپر نیچے

مختصر متغیر نام

جب ہمارے پاس متغیرات ہوتے ہیں جیسے x یا n یا اس طرح کی کوئی چیز، ہم فوری طور پر اس شخص کا ارادہ نہیں دیکھتے ہیں جس نے کوڈ لکھا ہے۔ یہ واضح نہیں ہے کہ n کیا کرتا ہے۔ اس کا پتہ لگانے کے لیے زیادہ محتاط غور و فکر کی ضرورت ہے (اور اس کا مطلب ہے وقت، وقت، وقت)۔ مثال کے طور پر، فرض کریں کہ ہمارے پاس ایک فیلڈ ہے جو ذمہ دار صارف کی شناخت کی نمائندگی کرتا ہے۔ کچھ متغیر نام جیسے x یا صرف id کے بجائے، ہم اس متغیر کو "responsibleUserId" کا نام دیں گے، جو فوری طور پر پڑھنے کی اہلیت اور معلوماتی مواد کو بہتر بناتا ہے۔ اس نے کہا، n جیسے مختصر ناموں کی جگہ چھوٹے طریقوں میں مقامی متغیرات کے طور پر ہوتی ہے، جہاں اس متغیر کو شامل کرنے والے کوڈ کا بلاک صرف چند لائنوں کا ہوتا ہے، اور طریقہ کا نام بالکل بیان کرتا ہے کہ وہاں کیا ہوتا ہے۔ ایسے متغیر کو دیکھ کر، ایک ڈویلپر سمجھتا ہے کہ یہ ثانوی اہمیت کا حامل ہے اور اس کی گنجائش بہت محدود ہے۔ نتیجے کے طور پر، دائرہ کار کا متغیر نام کی لمبائی پر ایک خاص انحصار ہوتا ہے: نام جتنا لمبا ہوگا، متغیر اتنا ہی عالمی ہوگا اور اس کے برعکس۔ مثال کے طور پر، تاریخ کے لحاظ سے آخری محفوظ شدہ صارف کو تلاش کرنے کا طریقہ یہ ہے:

public User findLastUser() {
   return findAllUsers().stream()
           .sorted((x, y) -> -x.getCreatedDate().compareTo(y.getCreatedDate()))
           .findFirst()
           .orElseThrow(() -> new ResourceNotFoundException("No user exists"));
}

یہاں ہم سٹریم کو ترتیب دینے کے لیے مختصر نام والے متغیرات x اور y استعمال کرتے ہیں، اور پھر ہم ان کے بارے میں بھول جاتے ہیں۔

بہترین لمبائی

آئیے نام کی لمبائی کے موضوع کے ساتھ جاری رکھیں۔ نام کی بہترین لمبائی n اور MaximumNumberOfUsersInTheCurrentGroup کے درمیان کہیں ہے۔ دوسرے لفظوں میں، مختصر نام معنی کی کمی کا شکار ہوتے ہیں، جب کہ جو نام بہت لمبے ہوتے ہیں وہ پڑھنے کی اہلیت کو شامل کیے بغیر پروگرام کو لمبا کرتے ہیں، اور ہم انہیں ہر بار لکھنے میں بہت سست ہوتے ہیں۔ n جیسے مختصر نام والے متغیرات کے لیے اوپر بیان کردہ کیس کے علاوہ، آپ کو تقریباً 8-16 حروف کی لمبائی پر قائم رہنا چاہیے۔ یہ کوئی سخت اصول نہیں ہے، صرف ایک رہنما اصول ہے۔

چھوٹے اختلافات

میں ناموں میں لطیف اختلافات کا ذکر کرنے میں ناکام نہیں رہ سکتا۔ یہ بھی ایک برا عمل ہے، کیونکہ یہ اختلافات محض الجھن کا باعث ہو سکتے ہیں یا ان پر توجہ دینے کے لیے بہت زیادہ وقت خرچ کرنے کی ضرورت ہے۔ مثال کے طور پر، InvalidDataAccessApiUsageException اور InvalidDataAccessResourceUsageException کے درمیان فرق کو ایک نظر میں دیکھنا مشکل ہے۔ چھوٹے حروف میں L اور O کا استعمال کرتے وقت اکثر کنفیوژن بھی پیدا ہو سکتی ہے، کیونکہ وہ آسانی سے 1 اور 0 کے لیے غلط ہو سکتے ہیں۔ کچھ فونٹس میں فرق زیادہ واضح ہوتا ہے، کچھ میں یہ کم ہوتا ہے۔

معنی

ہمیں ناموں کو معنی خیز بنانے کی ضرورت ہے، لیکن مترادفات کے ذریعے ابہام پیدا نہیں کرنا چاہیے، کیونکہ مثال کے طور پر، UserData اور UserInfo اصل میں ایک ہی معنی رکھتے ہیں۔ اس صورت میں، ہمیں کوڈ کی گہرائی میں کھودنا پڑے گا تاکہ یہ سمجھ سکیں کہ ہمیں کس خاص چیز کی ضرورت ہے۔ ایسے الفاظ سے پرہیز کریں جو مفید معلومات فراہم نہ کریں۔ مثال کے طور پر، firstNameString میں، ہمیں لفظ String کی ضرورت کیوں ہے؟ کیا یہ واقعی کوئی ڈیٹ آبجیکٹ ہو سکتا ہے؟ ہرگز نہیں۔ لہذا، ہم صرف firstName استعمال کرتے ہیں۔ میں بولین متغیرات کا بھی ذکر کرنا چاہوں گا۔ مثال کے طور پر، flagDeleted نامی ایک بولین لیں۔ جھنڈا لفظ کوئی معنی نہیں رکھتا۔ اسے isDeleted کہنا زیادہ معقول ہے۔

ڈس انفارمیشن

میں غلط ناموں کے کنونشنز کے بارے میں بھی کچھ الفاظ کہنا چاہوں گا۔ ہم کہتے ہیں کہ ہمارے پاس userActivityList کے نام سے ایک متغیر ہے، لیکن فہرست ہونے کے بجائے، یہ آبجیکٹ کسی دوسرے کنٹینر کی قسم یا کسٹم اسٹوریج آبجیکٹ ہے۔ یہ اوسط پروگرامر کو الجھا سکتا ہے: بہتر ہے کہ اسے یوزر ایکٹیویٹی گروپ یا یوزر ایکٹیویٹی جیسی کوئی چیز کہا جائے۔

تلاش کریں۔

مختصر اور سادہ ناموں میں سے ایک خامی یہ ہے کہ ان کو کوڈ کے بڑے حصے میں تلاش کرنا مشکل ہے — کون سا تلاش کرنا آسان ہوگا: "نام" یا "NAME_FOR_DEFAULT_USER"؟ دوسرا آپشن، بالکل. ہمیں ناموں میں کثرت سے آنے والے الفاظ (حروف) سے گریز کرنا چاہیے، کیونکہ وہ تلاش کے دوران صرف مماثل فائلوں کی تعداد میں اضافہ کریں گے، جو کہ اچھا نہیں ہے۔ میں آپ کو یاد دلانا چاہوں گا کہ پروگرامرز کوڈ کو لکھنے کے بجائے پڑھنے میں زیادہ وقت صرف کرتے ہیں، لہذا اپنی درخواست کے عناصر کو نام دینے کے بارے میں ہوشیار رہیں۔ لیکن اگر کوئی اچھا نام نہ ملے تو کیا ہوگا؟ اگر کسی طریقہ کا نام اس کی فعالیت کو اچھی طرح سے بیان نہیں کرتا ہے تو کیا ہوگا؟ یہ وہ جگہ ہے جہاں تبصرے مرحلے میں داخل ہوتے ہیں۔

تبصرے

مناسب تبصرے سے بہتر کوئی چیز نہیں ہے، لیکن کوئی بھی چیز خالی، فرسودہ، یا غلط تبصروں جیسے ماڈیول کو بے ترتیبی نہیں بناتی ہے۔ وہ دو دھاری تلوار ہو سکتے ہیں، نہیں؟ پھر بھی، آپ کو تبصروں کو غیر واضح طور پر اچھا نہیں سمجھنا چاہیے، بلکہ کم برائی سمجھنا چاہیے۔ سب کے بعد، ایک تبصرہ بنیادی طور پر اس سوچ کی تلافی کا ایک طریقہ ہے جو کوڈ میں واضح طور پر نہیں آتا ہے۔ مثال کے طور پر، اگر طریقہ بذات خود بہت مبہم نکلے تو ہم انہیں کسی نہ کسی طریقے کے جوہر کو بتانے کے لیے استعمال کرتے ہیں۔ اس صورت حال میں، وضاحتی نوٹ لکھنے سے بہتر ہے کہ کوڈ کو درست طریقے سے ری ایکٹر کیا جائے۔ تبصرہ جتنا پرانا ہوگا، تبصرہ اتنا ہی برا ہوگا، کیونکہ کوڈ بڑھتا اور تیار ہوتا ہے، لیکن تبصرے ایک جیسے رہ سکتے ہیں۔ تبصرہ بنائے جانے کے بعد جتنا زیادہ وقت گزرا ہے، اتنا ہی زیادہ قابل اعتراض ہوسکتا ہے۔ غلط تبصرے کسی بھی تبصرے سے کہیں زیادہ بدتر ہوتے ہیں، کیونکہ وہ مبہم اور فریب دینے والے ہوتے ہیں، غلط توقعات رکھتے ہیں۔ اور یہاں تک کہ اگر ہمارے پاس بہت مشکل کوڈ ہے، تو ہمیں اس پر تبصرہ کرنے کے بجائے اسے دوبارہ لکھنا چاہیے۔

تبصروں کی اقسام

• قانونی تبصرے - قانونی وجوہات کی بنا پر ہر سورس فائل کے شروع میں تبصرے، مثال کے طور پر:

  * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
  * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

• معلوماتی تبصرے - کوڈ کی وضاحت کی نمائندگی کرنے والے تبصرے (اضافی معلومات فراہم کرنا یا کوڈ کے دیئے گئے حصے کے ارادے کی وضاحت کرنا)۔

  مثال کے طور پر:

  /*
  * Combines the user from the database with the one passed for updating
  * When a field in requestUser is empty, it is filled with old data from foundUser
  */
  private User mergeUser(User requestUser, User foundUser) {
         return new User(
         foundUser.getId(),
         requestUser.getFirstName() == null ? requestUser.getFirstName() : foundUser.getFirstName(),
         requestUser.getMiddleName() == null ? requestUser.getMiddleName() : foundUser.getMiddleName(),
         requestUser.getLastName() == null ? requestUser.getLastName() : foundUser.getLastName(),
         requestUser.getAge() == null ? requestUser.getAge() : foundUser.getAge()
         );
         }

  اس صورت میں، آپ تبصرے کے بغیر کر سکتے ہیں، کیونکہ طریقہ کا نام اور اس کے پیرامیٹرز، بہت شفاف فعالیت کے ساتھ، خود کو اچھی طرح سے بیان کرتے ہیں.

• انتباہی تبصرے — تبصرے کا مقصد دوسرے ڈویلپرز کو کسی کارروائی کے ناپسندیدہ نتائج کے بارے میں متنبہ کرنا ہے (مثال کے طور پر، انہیں خبردار کرنا کہ ٹیسٹ کو @Ignore کے بطور نشان زد کیوں کیا گیا):

  // Takes too long to run
  // Don't run if you don't have a lot of time
  @Ignore
  @Test
  public void someIntegrationTest() {
         ……
         }

• TODO - تبصرے جو کسی ایسی چیز کے بارے میں ایک نوٹ ہیں جو مستقبل میں کرنے کی ضرورت ہے لیکن کسی وجہ سے ابھی نہیں کیا جا سکتا۔ یہ ایک اچھا عمل ہے، لیکن ایسے تبصروں کا باقاعدگی سے جائزہ لینا چاہیے تاکہ غیر متعلقہ کو ہٹایا جا سکے اور بے ترتیبی سے بچا جا سکے۔

  ایک مثال یہ ہوگی:

  // TODO: Add a check for the current user ID (when the security context is created)
  
  @Override
  public Resource downloadFile(File file) {
         return fileManager.download(file);
         }

  یہاں ہم اس حقیقت کو نوٹ کرتے ہیں کہ ہمیں ڈاؤن لوڈ آپریشن انجام دینے والے صارف کا موازنہ شامل کرنے کی ضرورت ہے (جس کی ID ہم سیکیورٹی کے تناظر سے نکالیں گے) اس کے ساتھ جس نے سیو آپریشن کیا۔

• تبصروں کو تقویت بخشتے ہیں - تبصرے جو کسی ایسے حالات کی اہمیت پر زور دیتے ہیں جو پہلی نظر میں غیر اہم معلوم ہو سکتا ہے۔

  مثال کے طور پر، اس طریقہ کار کے ایک ٹکڑے پر غور کریں جو ٹیسٹ ڈیٹا بیس کو کچھ اسکرپٹس سے بھرتا ہے:

  Stream.of(IOUtils.resourceToString("/fill-scripts/" + x, StandardCharsets.UTF_8)
         .trim()
         .split(";"))
         .forEach(jdbcTemplate::update);
  // The trim() call is very important. It removes possible spaces at the end of the script
  // so that when we read and split into separate requests, we don't end up with empty ones

• Javadoc تبصرے - تبصرے جو مخصوص فعالیت کے لیے API کی وضاحت کرتے ہیں۔ شاید سب سے زیادہ مفید تبصرے ہیں، کیونکہ دستاویزی API کے ساتھ کام کرنا بہت آسان ہے۔ اس نے کہا، وہ بھی کسی دوسرے قسم کے تبصرے کی طرح پرانے ہو سکتے ہیں۔ لہذا، یہ کبھی نہ بھولیں کہ دستاویزات میں بنیادی شراکت تبصروں سے نہیں، بلکہ اچھے کوڈ سے ہوتی ہے۔

  یہاں صارف کو اپ ڈیٹ کرنے کے لیے کافی عام طریقہ کی ایک مثال ہے:

  /**
  * Updates the passed fields for a user based on its id.
       *
  * @param id id of the user to be updated
  * @param user user with populated fields for updating
  * @return updated user
  */
         User update(Long id, User user);

برے تبصرے۔

• گڑبڑ کرنے والے تبصرے - وہ تبصرے جو عام طور پر جلدی میں لکھے جاتے ہیں اور جن کا مطلب صرف وہی ڈویلپر سمجھ سکتا ہے جس نے انہیں لکھا ہے، کیونکہ صرف وہی یا وہ اس اہم صورتحال کو سمجھتا ہے جس کی طرف تبصرہ کیا جاتا ہے۔

  اس مثال پر غور کریں:

  public void configureSomeSystem() {
         try{
         String configPath = filesLocation.concat("/").concat(CONFIGURATION_FILE);
         FileInputStream stream = new FileInputStream(configPath);
         } catch (FileNotFoundException e) {
         // If there is no configuration file, the default configuration is loaded
        }
  }

  ان ترتیبات کو کون لوڈ کرتا ہے؟ کیا وہ پہلے ہی لوڈ ہو چکے ہیں؟ کیا یہ طریقہ مستثنیات کو پکڑنے اور پہلے سے طے شدہ ترتیبات کو لوڈ کرنے والا ہے؟ بہت سارے سوالات پیدا ہوتے ہیں جن کا جواب صرف نظام کے دوسرے حصوں کی تحقیقات میں تلاش کرکے ہی دیا جاسکتا ہے۔

• بے کار تبصرے - ایسے تبصرے جو کوئی معنیاتی بوجھ نہیں اٹھاتے، کیونکہ کوڈ کے دیئے گئے حصے میں جو کچھ ہو رہا ہے وہ کافی حد تک واضح ہے۔ دوسرے الفاظ میں، تبصرہ کوڈ سے زیادہ پڑھنا آسان نہیں ہے۔

  آئیے ایک مثال دیکھتے ہیں:

  public class JdbcConnection{
  public class JdbcConnection{
     /**
      * The logger associated with the current class
      */
     private Logger log = Logger.getLogger(JdbcConnection.class.getName());
  
     /**
      * Creates and returns a connection using the input parameters
      */
     public static Connection buildConnection(String url, String login, String password, String driver) throws Exception {
         Class.forName(driver);
         connection = DriverManager.getConnection(url, login, password);
         log.info("Created connection with db");
         return connection;
     }

  ایسے تبصروں کا کیا فائدہ؟ وہ جو کچھ بھی بیان کرتے ہیں وہ پہلے ہی بالکل واضح ہے۔

• ناقابل اعتماد تبصرے - ایسے تبصرے جو غلط اور صرف گمراہ کن ہیں (غلط معلومات)۔ مثال کے طور پر، یہاں ایک ہے۔

  /**
  * Helper method. Closes the connection with the scanner if isNotUsing is true
  */
  private void scanClose(Scanner scan, boolean isNotUsing) throws Exception {
     if (!isNotUsing) {
         throw new Exception("The scanner is still in use");
     } scan.close();
  }

  اس تبصرے میں کیا حرج ہے؟ حقیقت یہ ہے کہ یہ ہمارے ساتھ تھوڑا سا جھوٹ بولتا ہے، اس میں کنکشن بند ہو جاتا ہے اگر isNotUsing غلط ہے، اس کے برعکس نہیں، جیسا کہ تبصرہ ہمیں مطلع کرتا ہے۔

• واجبی تبصرے - وہ تبصرے جو واجب سمجھے جاتے ہیں (مثلاً Javadoc تبصرے)، لیکن حقیقت میں بعض اوقات ضرورت سے زیادہ ڈھیر ہو جاتے ہیں اور ناقابل اعتبار اور غیر ضروری ہوتے ہیں (آپ کو یہ سوچنے کی ضرورت ہے کہ آیا ان تبصروں کی حقیقت میں ضرورت ہے)۔

مثال:

/**
* Create a user based on the parameters
* @param firstName first name of the created user
* @param middleName middle name of the created user
* @param lastName last name of the created user
* @param age age of the created user
* @param address address of the created user
* @return user that was created
*/
User createNewUser(String firstName, String middleName, String lastName, String age, String address);

کیا آپ یہ سمجھ سکیں گے کہ ان تبصروں کے بغیر طریقہ کار کیا کرتا ہے؟ زیادہ امکان ہے، ہاں، اس لیے تبصرے یہاں بے معنی ہو جاتے ہیں۔

• لاگ تبصرے - تبصرے جو کبھی کبھی کسی ماڈیول کے شروع میں ہر بار ترمیم کرنے پر شامل کیے جاتے ہیں (کچھ تبدیلی لاگ کی طرح)۔

  /**
  * Records kept since January 9, 2020;
  **********************************************************************
  * 9 Jan 2020: Providing a database connection using JDBC Connection;
  * 15 Jan 2020: Adding DAO-level interfaces for working with the database;
  * 23 Jan 2020: Adding integration tests for the database;
  * 28 Jan 2020: Implementation of DAO-level interfaces;
  * 1 Feb 2020: Development of interfaces for services,
  * in accordance with the requirements specified in user stories;
  * 16 Feb 2020: Implementation of service interfaces
  * (implementation of business logic related to the work of the database);
  * 25 Feb 2020: Adding tests for services;
  * 8 Mar 2020: Celebration of International Women's Day (Terry is drunk again);
  * 21 Mar 2020: Refactoring the service layer;
  */

  یہ نقطہ نظر ایک بار جائز تھا، لیکن ورژن کنٹرول سسٹم (مثال کے طور پر، Git) کی آمد کے ساتھ، یہ کوڈ کی ایک غیر ضروری بے ترتیبی اور پیچیدگی بن گئی۔

• تصنیف کے تبصرے - تبصرے جن کا مقصد اس شخص کی نشاندہی کرنا ہے جس نے کوڈ لکھا ہے، لہذا آپ اس سے رابطہ کر سکتے ہیں اور بحث کر سکتے ہیں کہ کیسے، کیا، اور کیوں، جیسے:

  * @author Bender Bending

  ایک بار پھر، ورژن کنٹرول سسٹم بالکل یاد رکھتے ہیں کہ کس نے کوڈ کا کوئی حصہ اور کب شامل کیا، اس لیے یہ نقطہ نظر ضرورت سے زیادہ ہے۔

• تبصرہ شدہ کوڈ - کوڈ جس پر کسی نہ کسی وجہ سے تبصرہ کیا گیا ہو۔ یہ بدترین عادتوں میں سے ایک ہے، کیونکہ کیا ہوتا ہے آپ کسی چیز پر تبصرہ کرتے ہیں اور اسے بھول جاتے ہیں، اور پھر دوسرے ڈویلپرز میں اسے حذف کرنے کی ہمت نہیں ہوتی ہے (آخر، کیا ہوگا اگر یہ کوئی قیمتی چیز ہے؟)

  //    public void someMethod(SomeObject obj) {
  //    .....
  //    }

  نتیجے کے طور پر، کمنٹ آؤٹ کوڈ ردی کی ٹوکری کی طرح جمع ہوتا ہے۔ کسی بھی صورت میں آپ کو ایسا کوڈ نہیں چھوڑنا چاہیے۔ اگر آپ کو واقعی اس کی ضرورت ہے تو، ورژن کنٹرول سسٹم کے بارے میں مت بھولنا۔

• غیر واضح تبصرے - ایسے تبصرے جو کسی چیز کو حد سے زیادہ پیچیدہ انداز میں بیان کرتے ہیں۔

  /*
      * Start with an array large enough to store
      * all the data bytes (plus filter bytes) with a cushion, plus 300 bytes
      * for header data
      */
  this.dataBytes = new byte[(this.size * (this.deep + 1) * 2)+300];

  ایک تبصرہ کوڈ کی وضاحت کرنی چاہئے۔ اسے خود وضاحت کی ضرورت نہیں ہونی چاہیے۔ تو یہاں کیا غلط ہے؟ "فلٹر بائٹس" کیا ہیں؟ وہ "+1" کیا ہے؟ بالکل 300 کیوں؟

اگر آپ نے پہلے ہی تبصرے لکھنے کا فیصلہ کر لیا ہے، تو یہاں چند تجاویز ہیں:

1. ایسے اسٹائلز کا استعمال کریں جو برقرار رکھنے میں آسان ہیں: ایسے اسٹائلز کو برقرار رکھنا جو بہت زیادہ فینسی اور غیر ملکی ہوں پریشان کن اور وقت طلب ہیں۔
2. لائن کے اختتامی تبصرے استعمال نہ کریں جو سنگل لائنوں کا حوالہ دیتے ہیں: نتیجہ تبصروں کا ایک بڑا ڈھیر ہے۔ مزید یہ کہ ہر سطر کے لیے معنی خیز تبصرہ سوچنا مشکل ہے۔
3. جب آپ کوئی تبصرہ لکھتے ہیں تو اس سوال کا جواب دینے کی کوشش کریں کہ "کیوں" کا جواب دینے کی کوشش کریں۔
4. مختصر معلومات سے گریز کریں۔ جیسا کہ میں نے اوپر کہا، ہمیں تبصرے کے لیے وضاحت کی ضرورت نہیں ہے: تبصرہ ہی وضاحت ہے۔
5. آپ اکائیوں اور قدر کی حدود کو نوٹ کرنے کے لیے تبصرے استعمال کر سکتے ہیں۔
6. تبصرے اس کوڈ کے قریب رکھیں جو وہ بیان کرتے ہیں۔

آخر میں، میں اب بھی آپ کو یاد دلانا چاہتا ہوں کہ بہترین تبصرہ کوئی تبصرہ نہیں ہے، بلکہ آپ کی درخواست کے دوران ہنر مند ناموں کا استعمال ہے۔ ایک اصول کے طور پر، زیادہ تر وقت ہم موجودہ کوڈ کے ساتھ کام کریں گے، اسے برقرار رکھنے اور اس میں توسیع کریں گے۔ جب یہ کوڈ پڑھنا اور سمجھنا آسان ہو تو یہ بہت زیادہ آسان ہوتا ہے، کیونکہ خراب کوڈ ایک رکاوٹ ہے۔ یہ کاموں میں رنچ پھینکنے کے مترادف ہے، اور جلد بازی اس کا وفادار ساتھی ہے۔ اور ہمارے پاس جتنا برا کوڈ ہے، کارکردگی اتنی ہی گرتی ہے۔ اس کا مطلب ہے کہ ہمیں وقتاً فوقتاً ری ایکٹر کرنے کی ضرورت ہے۔ لیکن اگر شروع سے ہی آپ کوڈ لکھنے کی کوشش کرتے ہیں جس کی وجہ سے اگلے ڈویلپرز آپ کو ڈھونڈنے اور مارنے کی خواہش نہیں کرتے ہیں، تو آپ کو اسے اکثر ری فیکٹر کرنے کی ضرورت نہیں ہوگی۔ لیکن یہ پھر بھی ضروری رہے گا، کیونکہ نئے انحصار اور کنکشن کے اضافے کے ساتھ مصنوعات کی شرائط اور تقاضے مسلسل بدلتے رہتے ہیں۔ ٹھیک ہے، مجھے لگتا ہے کہ آج میرے لئے یہ سب کچھ ہے۔ سب کا شکریہ جنہوں نے ابھی تک پڑھا ہے :)