ضابطا ضابطا: مناسب نالو ڏيڻ جي طاقت، سٺو ۽ خراب تبصرو

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

صحيح نالو ڏيڻ

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

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

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

ڪلاس جا نالا

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

طريقن جا نالا

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

متغير جا نالا

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

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

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

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

public User findLastUser() {
   return findAllUsers().stream()
           .sorted((x, y) -> -x.getCreatedDate().compareTo(y.getCreatedDate()))
           .findFirst()
           .orElseThrow(() -> new ResourceNotFoundException("Any user doesn't exist "));
}

ھتي اسان مختصر نالا استعمال ڪندا آھيون x ۽ y نديءَ جي ترتيب کي ترتيب ڏيڻ لاءِ، ۽ انھن جي باري ۾ وساريو.

بهترين ڊگھائي

اچو ته نالي جي طويل موضوع کي جاري رکون. وڌ ۾ وڌ نالي جي ڊگھائي ڪٿي آھي وڌ ۾ وڌNumberOfUsersInTheCurrentGroup نالي جي ڊگھائي ۽ n جي وچ ۾. اهو آهي ته، تمام ننڍا ماڻهو معنيٰ جي کوٽ جو شڪار آهن، ۽ تمام وڏا ماڻهو پڙهڻ جي قابليت ۾ اضافو ڪرڻ کان سواءِ پروگرام کي وڌائين ٿا، ۽ اهي هر ڀيري لکڻ ۾ بلڪل سست هوندا آهن. مٿئين صورت کي نظر ۾ نه رکندي، متغيرن لاءِ هڪ مختصر نالو جهڙوڪ n، توهان کي ڊيگهه رکڻ جي ضرورت آهي تقريبن 8 -16 اکرن تائين. هي هڪ سخت قاعدو نه آهي: وڌيڪ هدايتون.

ننڍا اختلاف

مان نالن ۾ ذيلي فرق کي نظر انداز نٿو ڪري سگهان، ڇاڪاڻ ته اهو پڻ هڪ خراب عمل آهي، ڇو ته توهان نالن ۾ معمولي اختلافن کي ڏسڻ ۾ صرف پريشان ٿي يا گهڻو وقت خرچ ڪري سگهو ٿا. مثال طور، InvalidDataAccessApiUsageException ۽ InvalidDataAccessResourceUsageException جي وچ ۾ فرق هڪ نظر ۾ ڳولڻ ڏکيو آهي. ان سان گڏ، غلط ڄاڻ اڪثر ڪري ٿي سگھي ٿو جڏهن ننڍي L ۽ O استعمال ڪندي، ڇاڪاڻ ته اهي آساني سان 1 ۽ 0 سان پريشان ٿي سگهن ٿيون: ڪجهه فونٽ ۾ فرق وڌيڪ واضح آهي، ٻين ۾ گهٽ.

معنيٰ وارو حصو

اسان کي نالن ۾ لفظي حصو رکڻو پوندو، پر مترادفات سان اوور پلے نه، ڇاڪاڻ ته، مثال طور، UserData ۽ UserInfo اصل ۾ هڪ ئي معنيٰ رکن ٿا، ۽ اسان کي ڪوڊ ۾ ٿوري گهڻي کوٽائي ڪرڻي پوندي ته اسان کي ڪهڙي خاص شئي جي ضرورت آهي. . غير معلوماتي لفظن کان پاسو ڪريو، مثال طور، firstNameString: اسان کي لفظ اسٽرنگ جي ضرورت ڇو آهي؟ ڇا نالو تاريخ جي قسم جو اعتراض ٿي سگھي ٿو؟ يقينا نه: تنهن ڪري، بس - پهريون نالو. مثال طور، مان بولان متغير جو ذڪر ڪرڻ چاهيندس، مثال طور، flagDelete. پرچم لفظ جي ڪا به معنيٰ نه آهي. ان کي سڏڻ وڌيڪ معقول ٿئي ها - isDelete.

اڻ ڄاڻائي

مان غلط نالي جي باري ۾ پڻ ڪجهه چوڻ چاهيندس. اچو ته چئون ته اسان وٽ نالو آهي userActivityList، ۽ نالو ڏنل اعتراض فهرست جي قسم جو ناهي، پر اسٽوريج لاء ڪجهه ٻيو ڪنٽينر يا ڪسٽم اعتراض آهي. اهو اوسط پروگرامر کي پريشان ڪري سگهي ٿو: اهو بهتر ٿيندو ته ان کي ڪجهه سڏين جهڙوڪ 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.

• معلوماتي تبصرا اهي تبصرا آهن جيڪي ڪوڊ جي وضاحت مهيا ڪن ٿا (اضافي معلومات مهيا ڪرڻ يا ڪوڊ جي ڏنل حصي جو ارادو.

  مثال طور:

  /*
  * Объединяет пользователя из бд и пришедшего для обновления
  * Когда в requestUser поле пустое, оно заполняется старыми данными из 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 طور نشان لڳايو ويو):

  // Слишком долго отрабатывает
  // Не запускайте, если не располагаете избытком времени
  @Ignore
  @Test
  public void someIntegrationTest() {
         ……
         }

• TODO - تبصرا جيڪي مستقبل لاءِ نوٽس آھن جيڪي ڪرڻ جي ضرورت پوندي، پر ڪجھ سببن لاءِ ھاڻي نه ٿي سگھي. اھو ھڪڙو سٺو عمل آھي، پر انھن کي اڃا تائين باقاعدي نظرثاني ڪرڻ جي ضرورت آھي غير لاڳاپيل ماڻھن کي ختم ڪرڻ لاءِ بي ترتيبي کان بچڻ لاءِ.

  Примером послужит:

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

  Тут мы помечаем, что нужно добавить проверку юзера, который скачивает (id которого мы вытащим из security контекста) с тем, кто сохранил.

• усorвающий комментарий — комментарий, подчеркивающий важность Howого-то обстоятельства, что на первый взгляд может показаться несущественным.

  Как пример, кусочек метода, заполняющий тестовую БД, некими скриптами:

  Stream.of(IOUtils.resourceToString("/fill-scripts/" + x, StandardCharsets.UTF_8)
         .trim()
         .split(";"))
         .forEach(jdbcTemplate::update);
  // Вызов trim() очень важен, убирает возможные пробелы в конце скрипта
  // чтобы при считке и разбивке на отдельные requestы не было пустых

• javaDoc — комментарии, которые описывают API определенного функционала для общего пользования. Наверное, самые полезные комментарии, так How с documentированным API в разы легче работать, но они также могут устаревать, How и любые другие. Поэтому не забываем, что главный вклад в documentацию вносится не комментариями, а хорошим codeом.

  Пример вполне обычного метода обновления пользователя:

  /**
  * Обновляет передаваемые поля для пользователя по id.
  *
  * @param id  id обновляемого пользователя
  * @param user пользователь с заполненными полями для обновления
  * @return обновленный пользователь
  */
         User update(Long id, User user);

Плохие сценарии комментариев

• бормочущий комментарий — комментарии, которые обычно пишут на скорую руку, смысл которых понятен только разработчику, писавшего их, так How только он видит ту ситуацию с теми нюансами, на которые он и ссылается.

  Рассмотрим данный пример:

  public void configureSomeSystem() {
         try{
         String configPath = filesLocation.concat("/").concat(CONFIGURATION_FILE);
         FileInputStream stream = new FileInputStream(configPath);
         }  catch (FileNotFoundException e) {
         //В случае отсутствия конфигурационного file, загружается конфигурация по умолчанию
        }
  }

  Кто загружает эти настройки? Были ли они загружены ранее? Метод предназначен для перехвата исключений и вызова дефолтных настроек? Слишком много вопросов возникает, ответы на которые можно получить лишь углубившись в изучение других частей системы.

• избыточный комментарий — комментарий, который не несёт смысловой нагрузки, так How и так понятно что происходит в заданном участке codeа (он читается не проще, чем code).

  Смотрим пример:

  public class JdbcConnection{
  public class JdbcConnection{
     /**
      * Журнальный компонент, связанный с текущим классом
      */
     private Logger log = Logger.getLogger(JdbcConnection.class.getName());
  
     /**
      * Создаёт и возвращает connection с помощью входящих параметров
      */
     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;
     }

  Какой смысл таких комментариев, если мы и так всё прекрасно видим

• недостоверные комментарии — комментарии, не соответствующие истине и лишь вгоняющие в заблуждение (дезинформирующие). Как например:

  /**
  * Вспомогательный метод, закрывает соединение со сканером, если isNotUsing истинно
  */
  private void scanClose(Scanner scan, boolean isNotUsing) throws Exception {
     if (!isNotUsing) {
         throw new Exception("The scanner is still in use");
     } scan.close();
  }

  What в этом комменте не так? А то, что он немножко врёт нам, ведь соединение закрывается, если isNotUsing = false, но ниHow не наоборот, How нам вещает пометка.

• обязательные комментарии — комментарии, которые считают обязательными (Javadoc), но кои по факту иногда бывают излишне нагромождающими, недостоверными и ненужными (нужно задуматься, а нужны ли здесь такие комментарии).

  Пример:

  /**
  *  Creation пользователя по переданным параметрам
  * @param firstName Name созданного пользователя
  * @param middleName среднее Name созданного пользователя
  * @param lastName фамorя созданного пользователя
  * @param age возраст созданного пользователя
  * @param address addressс созданного пользователя
  * @return пользователь который был создан
  */
  User createNewUser(String firstName, String middleName, String lastName, String age, String address);

  Смогли бы вы понять, что делает метод без этих комментариев? Скорее всего да, поэтому комментарии в этом случае стают бессмысленными.

• журнальные комментарии — комментарии, которые иногда добавляют в начало модуля, при каждом его редактировании (что-то вроде журнала вносимых изменений).

  /**
  *  Записи ведутся с 09 января 2020;
  **********************************************************************
  *  09.01.2020  : Обеспечение соединения с БД с помощью Jdbc Connection;
  *  15.01.2020  : Добавление интерфейсов уровня дао для работы с БД;
  *  23.01.2020  : Добавление интеграционных тестов для БД;
  *  28.01.2020  : Имплементация интерфейсов уровня дао;
  *  01.02.2020  : Разработка интерфейсов для сервисов,
  *  согласно требованиям прописанным в user stories;
  *  16.02.2020  : Имплементация интерфейсов сервисов
  *  (реализация бизнес логики связанной с работой БД);
  *  25.02.2020  : Добавление тестов для сервисов;
  *  08.03.2020  : Празднование восьмого марта(Миша опять в хлам);
  *  21.03.2020  : Рефакторинг сервис слоя;
  */

  Когда-то этот проход был оправдан, но с появлением систем управления исходным codeом (например — Git), это стало лишним нагромождением и усложнением codeа.

• комментарии ссылки на авторов — комментарии, преднаmeaningм которых является, указание человека, писавшего code, чтобы можно было связаться и обсудить, How что и зачем:

  * @author  Bender Benderovich

  Опять же, системы контроля версий прекрасно запоминают, кто и когда добавил данный code, и подобный подход излишен.

• تبصرو ڪوڊ ڪوڊ آهي جيڪو هڪ سبب يا ٻئي لاءِ تبصرو ڪيو ويو آهي. بدترين عادتن مان هڪ، ڇاڪاڻ ته توهان ان کي تبصرو ڪيو ۽ وساري ڇڏيو، ۽ ٻين ڊولپرز کي صرف ان کي ختم ڪرڻ جي جرئت نه آهي (ڇا اهو ڪجهه قيمتي آهي).

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

  نتيجي طور، اهو ڪچري وانگر گڏ ٿئي ٿو. ڪنهن به حالت ۾ اهڙو ڪوڊ نه ڇڏڻ گهرجي. جيڪڏهن توهان کي واقعي جي ضرورت آهي، نه وساريو نسخو ڪنٽرول سسٽم بابت.

• غير واضح تبصرا اهي تبصرا آهن جيڪي ڪجهه غير ضروري پيچيده انداز ۾ بيان ڪن ٿا.

  /*
      * Начать с массива, размер которого достаточен для хранения
      * всех byteов данных (плюс byteы фильтра) с запасом, плюс 300 byte
      * для данных заголовка
      */
  this.dataBytes = new byte[(this.size * (this.deep + 1) * 2)+300];

  هڪ تبصرو ڪوڊ جي وضاحت ڪرڻ گهرجي، وضاحت جي ضرورت ناهي. هتي ڇا ٿي رهيو آهي؟ ڇا آهن "فلٽر بائيٽ"؟ +1 جو هن سان ڇا تعلق آهي؟ ڇو بلڪل 300؟

جيڪڏهن توهان رايا لکڻ جو فيصلو ڪيو، هتي انهن کي استعمال ڪرڻ لاء ڪجهه طريقا آهن:

1. اسٽائل استعمال ڪريو جيڪي برقرار رکڻ ۾ آسان آهن: طرزن کي برقرار رکڻ جيڪي ڏاڍا فينسي ۽ ڌار ڌار هوندا آهن پريشان ڪندڙ ۽ وقت وٺندڙ.
2. سٽون جي آخر ۾ تبصرا استعمال نه ڪريو جيڪي واحد لائينن ڏانهن اشارو ڪن ٿا: هي تبصرن جو هڪ وڏو انبار ٺاهي ٿو، ۽ اهو ڏکيو آهي ته هر لڪير لاء هڪ اظهار ڪندڙ تبصرو سان گڏ.
3. جڏهن هڪ تبصرو ٺاهيو، سوال جو جواب ڏيڻ جي ڪوشش ڪريو "ڇو" بجاء "ڪيئن".
4. مخففات کان پاسو ڪريو. جيئن مون مٿي چيو آهي، اسان کي تبصري جي وضاحت جي ضرورت ناهي: تبصرو وضاحت آهي.
5. توھان استعمال ڪري سگھوٿا تبصرا ماپ جي يونٽن ۽ قابل قبول قدرن جي حد کي نشانو بڻائڻ لاءِ.
6. انهن جي بيان ڪيل ڪوڊ جي ويجهو رايا رکو.

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