ڪوڊنگ ضابطا: صحيح نالن جي طاقت، سٺو ۽ خراب تبصرا

توهان کي ڪيترا ڀيرا ڪنهن ٻئي جي ڪوڊ ۾ کڙو ڪرڻو پوندو؟ ٻن ڪلاڪن جي بدران، توهان ٻه ڏينهن خرچ ڪري سگهو ٿا صرف منطق کي سمجهڻ لاء ڇا ٿي رهيو آهي. عجيب ڳالهه اها آهي ته ان شخص لاءِ جنهن ڪوڊ لکيو، هر شيءِ صاف ۽ مڪمل شفاف آهي. اها تعجب جي ڳالهه ناهي: سڀ کان پوء، مڪمل ڪوڊ هڪ تمام غير واضح تصور آهي، ڇاڪاڻ ته هر ڊولپر کي دنيا ۽ ڪوڊ جو پنهنجو خواب آهي. مان هڪ کان وڌيڪ ڀيرا اهڙي صورتحال ۾ آيو آهيان جڏهن هڪ همراهه ۽ مون هڪ ئي ڪوڊ کي ڏٺو ۽ ان جي درستي ۽ صفائي بابت مختلف رايا هئا. آواز واقف، ڇا اهو ناهي؟ اڃا تائين، ڪجھ وقت جي آزمائشي اصول آھن جن تي عمل ڪرڻ گھرجي. آخر ۾، اهي توهان لاء فائدي وارا هوندا، ڇاڪاڻ ته جيڪڏهن توهان پنهنجو ڪوڊ ان حالت ۾ ڇڏي ڏيو جنهن ۾ توهان پاڻ ان کي حاصل ڪرڻ چاهيو ٿا، ته پوء دنيا ٿوري خوش ۽ صاف ٿي ويندي. اسان جي پوئين مضمون ۾ (يا بلڪه، ننڍڙو گائيڊ) ڪوڊنگ جي ضابطن بابت، اسان کي مڪمل طور تي سسٽم لکڻ ۽ ان جي اجزاء حصن، جهڙوڪ شيون، انٽرفيس، ڪلاس، طريقا، ۽ متغيرن لاء سفارشون جو ٿورو احساس مليو. انهي ساڳئي مضمون ۾، مون اتفاق سان ڪجهه عناصر جي صحيح نالو جو ذڪر ڪيو. مان اڄ ان بابت ڳالهائڻ چاهيندس، ڇاڪاڻ ته صحيح نالا ڪوڊ کي ڪيترائي ڀيرا پڙهڻ ۾ آسان بڻائي ٿو. اسان صحيح ڪوڊ جي موضوع کي ڪجهه عڪاسي سان بند ڪنداسين، ڪوڊ ۾ تبصرن جا ننڍا مثال، ۽ غور ڪيو ته ڇا اهو سٺو آهي يا نه ايترو سٺو. خير، اچو ته شروع ڪريون.

صحيح نالا

صحيح نالا ڪوڊ پڙهڻ جي صلاحيت کي بهتر بڻائي ٿو، اهڙيء طرح ڪوڊ سان پاڻ کي واقف ڪرڻ لاء گهربل وقت گھٽائي ٿو، ڇاڪاڻ ته هڪ طريقو استعمال ڪرڻ تمام آسان آهي جڏهن ان جو نالو تقريبا ان جي ڪارڪردگي کي بيان ڪري ٿو. ڪوڊ ۾ هر شي نالن تي مشتمل آهي (متغير، طريقا، ڪلاس، شيون، فائلون، وغيره)، تنهنڪري اهو نقطو تمام ضروري آهي جڏهن صحيح، صاف ڪوڊ ٺاهي. مٿين بنيادن تي، نالو معني ڏيڻ گهرجي، مثال طور، ڇو متغير موجود آهي، اهو ڇا ڪندو آهي، ۽ اهو ڪيئن استعمال ڪيو ويندو آهي. مان هڪ کان وڌيڪ ڀيرا نوٽ ڪندس ته هڪ متغير لاءِ بهترين تبصرو اهو آهي ته ان کي سٺو نالو ڏيو.

ٽي وي سيريز "Sherlock" مان (2010-2017)

نالو ڏيڻ واري انٽرفيس

انٽرفيس ۾ عام طور تي نالا هوندا آهن جيڪي ڪيپيٽل اکر سان شروع ٿيندا آهن ۽ ڪيمل ڪيس ۾ لکيل هوندا آهن. انٽرفيس لکڻ وقت، ان کي انٽرفيس (مثال طور، IUserService) مقرر ڪرڻ لاءِ اڳياڙي ”I“ شامل ڪرڻ لاءِ سٺو عمل سمجهيو ويندو هو، پر اهو ڏسڻ ۾ ڪافي بدصورت ۽ پريشان ڪندڙ آهي. اهڙين حالتن ۾، اهو بهتر آهي ته پريفڪس (UserService) کي ختم ڪيو وڃي ۽ "Impl" کي ان جي نفاذ جي نالي سان لافاني طور شامل ڪيو وڃي (مثال طور UserServiceImpl). يا ممڪن طور تي، آخري حل جي طور تي، لاڳو ڪرڻ جي نالي تي "C" اڳياڙي شامل ڪريو (مثال طور CUserService).

ڪلاس جا نالا

بس انٽرفيس وانگر، طبقي جا نالا سرمائيدار آهن ۽ CamelCase استعمال ڪريو. اهو مسئلو ناهي ته اسان هڪ زومبي apocalypse کي منهن ڏئي رهيا آهيون، اهو مسئلو ناهي ته آخر هٿ ۾ آهي - ڪڏهن به، ڪڏهن به، ڪڏهن به ڪنهن طبقي جو نالو فعل نه هجڻ گهرجي! ڪلاس ۽ اعتراض جا نالا اسم يا مرڪب اسم هجڻ گهرجن (UserController، User Details، UserAccount، وغيره). توهان کي هر طبقي جي نالي جي آخر ۾ ايپليڪيشن جو مخفف نه رکڻ گهرجي، ڇو ته اهو صرف غير ضروري پيچيدگي شامل ڪندو. مثال طور، جيڪڏهن اسان وٽ هڪ صارف ڊيٽا لڏپلاڻ واري ايپليڪيشن آهي، ته پوءِ مهرباني ڪري هر ڪلاس ۾ "UDM" شامل نه ڪريو، يعني UDMUserDetails، UDMUserAccount، UDMUserController.

طريقن جا نالا

عام طور تي، طريقن جا نالا هڪ ننڍڙي اکر سان شروع ٿين ٿا، پر اهي پڻ اٺن جي صورت جو انداز (ڪيمل ڪيس) استعمال ڪندا آهن. مٿي، اسان چيو ته طبقي جا نالا ڪڏهن به فعل نه ٿيڻ گهرجن. هتي صورتحال بلڪل برعڪس آهي: طريقن جا نالا فعل يا فعل جا جملا هجن: findUserById، FindAllUsers، createUser، وغيره. جڏهن هڪ طريقو ٺاهيو (انهي سان گڏوگڏ متغير ۽ طبقن)، تنهن ڪري مونجهاري کان بچڻ لاء هڪ مسلسل نالو ڪنوينشن استعمال ڪريو. مثال طور، هڪ صارف ڳولڻ لاء، هڪ طريقو نالو ٿي سگهي ٿو getUserById يا findUserById. ۽ هڪ ٻي شيء: طريقن جي نالن ۾ مزاح استعمال نه ڪريو، ڇاڪاڻ ته ٻيا شايد مذاق نه سمجهي سگھندا. نتيجي طور، اھي سمجھڻ ۾ ناڪام ٿي سگھي ٿو ته طريقو ڇا آھي.

متغير جا نالا

اڪثر صورتن ۾، متغير جا نالا هڪ ننڍي اکر سان شروع ٿين ٿا ۽ CamelCase پڻ استعمال ڪن ٿا، سواءِ جڏهن متغير هڪ عالمي مستقل هجي. اهڙين حالتن ۾، نالي جا سڀئي اکر اپر اکر ۾ لکيا ويندا آهن ۽ لفظن کي انڊر اسڪور ("_") سان الڳ ڪيو ويندو آهي. سھولت لاءِ، توھان استعمال ڪري سگھوٿا معنيٰ وارو حوالو جڏھن متغيرن جو نالو ڏيو. ٻين لفظن ۾، جڏهن هڪ متغير ڪنهن وڏي شيءِ جي حصي طور موجود هجي، مثال طور، پهريون نالو، آخري نالو، يا حيثيت. اهڙين حالتن ۾، توهان هڪ اڳوڻو شامل ڪري سگهو ٿا جيڪو ظاهر ڪري ٿو اعتراض جنهن سان هي متغير تعلق رکي ٿو. مثال طور: userFirstName، userLastName، userStatus. توهان کي به ساڳيون نالن کان پاسو ڪرڻ گهرجي متغيرن لاءِ جڏهن اهي مڪمل طور تي مختلف معنائون رکن. ھتي آھن ڪجھ اڪثر سامھون متغير نالن ۾ استعمال ٿيل متضاد لفظ:

• شروعات / پڇاڙي
• پهريون آخري
• بند ٿيل / کليل
• منٽ / وڌ ۾ وڌ
• اڳيون/اڳيون
• پراڻو/ نئون
• کليل/بند
• ظاهر / پوشیدہ
• ذريعو/هدف
• ذريعو / منزل
• لاهيون چاڙهيون

مختصر متغير جا نالا

جڏهن اسان وٽ متغير آهن جهڙوڪ 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 جي ضرورت ڇو آهي؟ ڇا اهو واقعي هڪ تاريخ اعتراض ٿي سگهي ٿو؟ بلڪل نه. تنهن ڪري، اسان صرف پهريون نالو استعمال ڪندا آهيون. مان پڻ بولان متغير جو ذڪر ڪرڻ چاهيندس. مثال طور، هڪ بوليان نالو وٺي flagDeleted. پرچم لفظ جي ڪا به معنيٰ ناهي. اهو وڌيڪ معقول آهي ته ان کي حذف ڪيو ويو آهي.

اڻ ڄاڻائي

مان غلط نالي جي ڪنوينشن بابت پڻ ڪجھ چوڻ چاهيندس. اچو ته چئون ته اسان وٽ هڪ ويريئبل آهي جنهن جو نالو userActivityList آهي، پر هڪ List ٿيڻ بدران، هي اعتراض ڪنهن ٻئي ڪنٽينر جو قسم يا ڪسٽم اسٽوريج آبجیکٹ آهي. اهو اوسط پروگرامر کي پريشان ڪري سگهي ٿو: اهو بهتر آهي ته ان کي ڪجهه سڏين جهڙوڪ userActivityGroup يا userActivities.

ڳولا

مختصر ۽ سادو نالن جي هڪ خرابي اها آهي ته انهن کي ڪوڊ جي وڏي حصي ۾ ڳولڻ ڏکيو آهي - ڪهڙو ڳولڻ آسان ٿيندو: "نالو" يا "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 غلط آهي، نه ان جي برعڪس، جيئن تبصرو اسان کي خبر ڏئي ٿو.

• واجبي تبصرا - تبصرا جيڪي واجب سمجهيا وڃن ٿا (مثال طور جاواڊڪ تبصرا)، پر حقيقت ۾ ڪڏهن ڪڏهن تمام گهڻو ۽ ناقابل اعتبار ۽ غير ضروري آهي (توهان کي سوچڻ جي ضرورت آهي ته اهي تبصرا حقيقت ۾ گهربل آهن).

مثال:

/**
* 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;
  */

  اهو طريقو هڪ ڀيرو صحيح ثابت ٿيو، پر نسخي ڪنٽرول سسٽم جي آمد سان (مثال طور، گٽ)، اهو ڪوڊ جي هڪ غير ضروري خرابي ۽ پيچيدگي بڻجي ويو.

• ليکڪ تبصرا - تبصرا جن جو مقصد ان شخص جي نشاندهي ڪرڻ آهي جنهن ڪوڊ لکيو آهي، تنهنڪري توهان ان سان رابطو ڪري سگهو ٿا ۽ بحث ڪري سگهو ٿا ڪيئن، ڇا، ۽ ڇو، مثال طور:

  * @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. انهن جي بيان ڪيل ڪوڊ جي ويجهو رايا رکو.

آخرڪار، مان اڃا تائين توهان کي ياد ڏيارڻ چاهيان ٿو ته بهترين تبصرو ڪو به تبصرو نه آهي، بلڪه توهان جي ايپليڪيشن ۾ مهارت رکندڙ نالو استعمال ڪرڻ. ضابطي جي طور تي، اڪثر وقت اسان موجوده ڪوڊ سان ڪم ڪنداسين، ان کي برقرار رکڻ ۽ وڌائڻ. اهو تمام گهڻو آسان آهي جڏهن هي ڪوڊ پڙهڻ ۽ سمجهڻ آسان آهي، ڇاڪاڻ ته خراب ڪوڊ هڪ رڪاوٽ آهي. اهو ڪم ۾ رنچ اڇلائڻ وانگر آهي، ۽ جلدي ان جو وفادار ساٿي آهي. ۽ اسان وٽ وڌيڪ خراب ڪوڊ، وڌيڪ ڪارڪردگي گهٽجي. هن جو مطلب آهي ته اسان کي وقت وقت تي refactor ڪرڻ جي ضرورت آهي. پر جيڪڏهن شروع کان ئي توهان ڪوڊ لکڻ جي ڪوشش ڪندا ته ايندڙ ڊولپرز توهان کي ڳولڻ ۽ مارڻ جو سبب نه بڻجندا، ته پوءِ توهان کي ان کي بار بار ريفيڪٽر ڪرڻ جي ضرورت نه پوندي. پر اهو اڃا به ضروري هوندو، ڇاڪاڻ ته پيداوار جون حالتون ۽ گهرجون مسلسل نئين انحصار ۽ ڪنيڪشن جي اضافي سان تبديل ٿينديون آهن. چڱو، مان سمجهان ٿو ته اهو سڀ ڪجهه اڄ مون لاء آهي. هر ڪنهن جي مهرباني جنهن هن پري پڙهيو :)