कोडिंग नियम: सही नाम, अच्छी और बुरी टिप्पणियों की शक्ति

आपको कितनी बार किसी और के कोड में खोदना पड़ा है? क्या हो रहा है इसके तर्क को समझने के लिए आप दो घंटे के बजाय दो दिन खर्च कर सकते हैं। मजेदार बात यह है कि कोड लिखने वाले व्यक्ति के लिए सब कुछ स्पष्ट और पूरी तरह से पारदर्शी है। यह आश्चर्य की बात नहीं है: आखिरकार, सही कोड एक बहुत ही अस्पष्ट अवधारणा है, क्योंकि प्रत्येक डेवलपर की दुनिया और कोड की अपनी दृष्टि भी होती है। एक से अधिक बार मैं ऐसी स्थिति में रहा हूं जब एक सहकर्मी और मैंने एक ही कोड को देखा और इसकी शुद्धता और शुद्धता के बारे में अलग-अलग राय थी।परिचित लगता है, है ना? फिर भी, कुछ समय-परीक्षणित सिद्धांत हैं जिनका पालन किया जाना चाहिए। अंत में, वे आपके लिए फायदेमंद होंगे, क्योंकि यदि आप अपना कोड उस स्थिति में छोड़ देते हैं जिसमें आप स्वयं इसे प्राप्त करना चाहते हैं, तो दुनिया थोड़ी खुश और स्वच्छ हो जाएगी। हमारे पिछले लेख में(या बल्कि, छोटी गाइड) कोडिंग नियमों के बारे में, हमें संपूर्ण और उसके घटक भागों, जैसे ऑब्जेक्ट्स, इंटरफेस, क्लासेस, मेथड्स और वेरिएबल्स के रूप में एक सिस्टम लिखने के लिए सिफारिशों की थोड़ी समझ मिली। उसी लेख में, मैंने आकस्मिक रूप से कुछ तत्वों के सही नामकरण का उल्लेख किया। मैं आज इसके बारे में बात करना चाहूंगा, क्योंकि सही नाम कोड को पढ़ने में कई गुना आसान बनाते हैं। हम कुछ प्रतिबिंबों, कोड में टिप्पणियों के छोटे उदाहरणों और यह अच्छा है या नहीं, इस पर विचार करके सही कोड के विषय को समाप्त कर देंगे। खैर, चलिए शुरू करते हैं।

सही नाम

सही नाम कोड की पठनीयता में सुधार करते हैं, इस प्रकार कोड के साथ खुद को परिचित करने के लिए आवश्यक समय को कम करते हैं, क्योंकि एक विधि का उपयोग करना बहुत आसान होता है जब इसका नाम मोटे तौर पर इसकी कार्यक्षमता का वर्णन करता है। कोड में सब कुछ नाम (चर, विधियों, वर्गों, वस्तुओं, फ़ाइलों आदि) से बना होता है, इसलिए सही, स्वच्छ कोड बनाते समय यह बिंदु बहुत महत्वपूर्ण हो जाता है। उपरोक्त के आधार पर, नाम को अर्थ बताना चाहिए, उदाहरण के लिए, वेरिएबल क्यों मौजूद है, यह क्या करता है, और इसका उपयोग कैसे किया जाता है। मैं एक से अधिक बार ध्यान दूंगा कि एक चर के लिए सबसे अच्छी टिप्पणी यह ​​है कि इसे एक अच्छा नाम दिया जाए।

टीवी-श्रृंखला "शर्लक" से (2010-2017)

नामकरण इंटरफेस

इंटरफ़ेस में आमतौर पर ऐसे नाम होते हैं जो बड़े अक्षर से शुरू होते हैं और CamelCase में लिखे जाते हैं। इंटरफ़ेस लिखते समय, इसे एक इंटरफ़ेस के रूप में नामित करने के लिए "I" उपसर्ग जोड़ने के लिए अच्छा अभ्यास माना जाता था (उदाहरण के लिए, IUserService), लेकिन यह बहुत बदसूरत और विचलित करने वाला लगता है। ऐसे मामलों में, उपसर्ग (उपयोगकर्ता सेवा) को छोड़ना और इसके कार्यान्वयन के नाम में "Impl" को प्रत्यय के रूप में जोड़ना बेहतर होता है (उदाहरण के लिए UserServiceImpl)। या संभवतः, अंतिम उपाय के रूप में, कार्यान्वयन के नाम में "सी" उपसर्ग जोड़ें (उदाहरण के लिए CUserService)।

वर्ग के नाम

इंटरफ़ेस की तरह, वर्ग के नाम बड़े अक्षरों में होते हैं और CamelCase का उपयोग करते हैं। इससे कोई फर्क नहीं पड़ता कि हम ज़ोंबी सर्वनाश का सामना कर रहे हैं, इससे कोई फर्क नहीं पड़ता कि अंत हाथ में है - कभी नहीं, कभी नहीं, कभी भी कक्षा का नाम क्रिया नहीं होना चाहिए! वर्ग और वस्तु के नाम संज्ञा या यौगिक संज्ञा (उपयोगकर्ता नियंत्रक, उपयोगकर्ता विवरण, उपयोगकर्ता खाता, और इसी तरह) होना चाहिए। आपको प्रत्येक वर्ग के नाम के अंत में आवेदन का संक्षिप्त नाम नहीं लगाना चाहिए, क्योंकि इससे केवल अनावश्यक जटिलता बढ़ेगी। उदाहरण के लिए, यदि हमारे पास उपयोगकर्ता डेटा माइग्रेशन एप्लिकेशन है, तो कृपया प्रत्येक वर्ग, यानी UDMUserDetails, UDMUserAccount, UDMUserController में "UDM" न जोड़ें।

विधि के नाम

आमतौर पर, विधि के नाम लोअरकेस अक्षर से शुरू होते हैं, लेकिन वे कैमल केस स्टाइल (कैमलकेस) का भी उपयोग करते हैं। ऊपर, हमने कहा कि वर्ग के नाम कभी भी क्रिया नहीं होने चाहिए। यहां स्थिति बिल्कुल विपरीत है: विधियों के नाम क्रिया या क्रिया वाक्यांश होने चाहिए: FindUserById, FindAllUsers, createUser, और इसी तरह। एक विधि (साथ ही चर और कक्षाएं) बनाते समय, इसलिए भ्रम से बचने के लिए एक सुसंगत नामकरण परंपरा का उपयोग करें। उदाहरण के लिए, एक उपयोगकर्ता को खोजने के लिए, एक विधि का नाम getUserById या FindUserById हो सकता है। और एक बात और: विधियों के नाम पर हास्य का प्रयोग न करें, क्योंकि हो सकता है कि दूसरे लोग मजाक को न समझें। नतीजतन, वे यह समझने में विफल हो सकते हैं कि विधि क्या करती है।

चर नाम

ज्यादातर मामलों में, चर नाम एक लोअरकेस अक्षर से शुरू होते हैं और कैमलकेस का भी उपयोग करते हैं, सिवाय इसके कि जब चर एक वैश्विक स्थिरांक हो। ऐसे मामलों में, नाम के सभी अक्षर अपरकेस में लिखे जाते हैं और शब्दों को एक अंडरस्कोर ("_") द्वारा अलग किया जाता है। सुविधा के लिए, चरों का नामकरण करते समय आप सार्थक संदर्भ का उपयोग कर सकते हैं। दूसरे शब्दों में, जब कोई चर किसी बड़ी चीज़ के भाग के रूप में मौजूद होता है, उदाहरण के लिए, FirstName, LastName, या स्थिति। ऐसे मामलों में, आप एक उपसर्ग जोड़ सकते हैं जो उस वस्तु को इंगित करता है जिससे यह चर संबंधित है। उदाहरण के लिए: userFirstName, userLastName, userStatus। आपको वेरिएबल्स के लिए समान नामों से भी बचना चाहिए जब उनके पूरी तरह से अलग अर्थ हों। यहाँ चर नामों में उपयोग किए जाने वाले कुछ समानार्थक शब्द हैं:

• शुरू/समाप्ति
• पहला अंतिम
• लॉक / अनलॉक
• न्यूनतम अधिकतम
• अगला पिछला
• पुराना नया
• खोला/बंद
• दृश्यमान / अदृश्य
• सोर्स टारगेट
• मूल गंतव्य
• ऊपर नीचे

लघु चर नाम

जब हमारे पास x या n या ऐसा कुछ चर होता है, तो हम कोड लिखने वाले व्यक्ति के इरादे को तुरंत नहीं देखते हैं। यह स्पष्ट नहीं है कि n क्या करता है। यह पता लगाने के लिए अधिक सावधानीपूर्वक चिंतन की आवश्यकता है (और इसका अर्थ है समय, समय, समय)। उदाहरण के लिए, मान लें कि हमारे पास एक ऐसा क्षेत्र है जो जिम्मेदार उपयोगकर्ता की आईडी का प्रतिनिधित्व करता है। कुछ चर नाम जैसे x या बस आईडी के बजाय, हम इस चर को "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 और maxNumberOfUsersInTheCurrentGroup के बीच कहीं है। दूसरे शब्दों में, छोटे नाम अर्थ की कमी से पीड़ित होते हैं, जबकि बहुत लंबे नाम बिना पठनीयता जोड़े कार्यक्रम को लंबा कर देते हैं, और हम उन्हें हर बार लिखने के लिए बहुत आलसी होते हैं। एन जैसे संक्षिप्त नाम वाले चर के लिए ऊपर वर्णित मामले के अलावा, आपको लगभग 8-16 वर्णों की लंबाई तक रहना चाहिए। यह कोई सख्त नियम नहीं है, सिर्फ एक दिशानिर्देश है।

छोटे अंतर

मैं नामों में सूक्ष्म अंतरों का उल्लेख करने में विफल नहीं हो सकता। यह भी एक बुरा अभ्यास है, क्योंकि ये अंतर केवल भ्रमित करने वाले हो सकते हैं या उन्हें नोटिस करने के लिए बहुत अधिक अतिरिक्त समय खर्च करने की आवश्यकता होती है। उदाहरण के लिए, InvalidDataAccessApiUsageException और InvalidDataAccessResourceUsageException के बीच का अंतर एक नज़र में पहचानना मुश्किल है। लोअरकेस एल और ओ का उपयोग करते समय अक्सर भ्रम भी उत्पन्न हो सकता है, क्योंकि उन्हें 1 और 0 के लिए आसानी से गलत किया जा सकता है। कुछ फोंट में अंतर अधिक स्पष्ट होता है, कुछ में यह कम होता है।

अर्थ

हमें नामों को सार्थक बनाने की आवश्यकता है, लेकिन समानार्थी शब्दों के माध्यम से अस्पष्टता पैदा नहीं करनी चाहिए, उदाहरण के लिए, UserData और UserInfo का वास्तव में एक ही अर्थ है। इस मामले में, हमें यह समझने के लिए कोड में गहरी खुदाई करनी होगी कि हमें किस विशेष वस्तु की आवश्यकता है। उन शब्दों से बचें जो उपयोगी जानकारी नहीं देते हैं। उदाहरण के लिए, FirstNameString में, हमें स्ट्रिंग शब्द की आवश्यकता क्यों है? क्या यह वास्तव में दिनांक वस्तु हो सकती है? बिल्कुल नहीं। तो, हम केवल फर्स्टनाम का उपयोग करते हैं। मैं बूलियन चर का भी उल्लेख करना चाहूंगा। उदाहरण के तौर पर, फ्लैगडिलीटेड नामक बूलियन लें। ध्वज शब्द का कोई अर्थ नहीं है। इसे हटा दिया गया कहना अधिक उचित है।

दुष्प्रचार

मैं गलत नामकरण परिपाटियों के बारे में भी कुछ शब्द कहना चाहूंगा। मान लें कि हमारे पास 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.
  

• जानकारीपूर्ण टिप्पणियाँ - कोड की व्याख्या का प्रतिनिधित्व करने वाली टिप्पणियाँ (अतिरिक्त जानकारी प्रदान करना या कोड के दिए गए अनुभाग के इरादे पर विस्तार करना)।

  उदाहरण के लिए:

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

  यहां हम इस तथ्य पर ध्यान देते हैं कि हमें डाउनलोड ऑपरेशन करने वाले उपयोगकर्ता की तुलना करने की आवश्यकता है (जिसकी आईडी हम सुरक्षा संदर्भ से निकालेंगे) जिसने सेव ऑपरेशन किया था।

• टिप्पणियों पर लगाम लगाना - ऐसी परिस्थिति के महत्व पर बल देने वाली टिप्पणियाँ जो पहली नज़र में महत्वहीन लग सकती हैं।

  एक उदाहरण के रूप में, एक विधि के एक टुकड़े पर विचार करें जो कुछ लिपियों के साथ एक परीक्षण डेटाबेस भरता है:

  
  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 का वर्णन करती हैं। संभवतः सबसे उपयोगी टिप्पणियाँ हैं, क्योंकि प्रलेखित एपीआई के साथ काम करना बहुत आसान है। उस ने कहा, वे भी किसी अन्य प्रकार की टिप्पणी की तरह पुराने हो सकते हैं। इसलिए, यह कभी न भूलें कि प्रलेखन में मुख्य योगदान टिप्पणियों द्वारा नहीं, बल्कि अच्छे कोड द्वारा किया जाता है।

  यहां उपयोगकर्ता को अपडेट करने के लिए काफी सामान्य विधि का एक उदाहरण दिया गया है:

  
  /**
  * 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();
  }
  

  इस टिप्पणी में गलत क्या है? तथ्य यह है कि यह हमारे लिए थोड़ा झूठ है, इसमें कनेक्शन बंद है यदि उपयोग नहीं किया जा रहा है, गलत है, इसके विपरीत नहीं, जैसा कि टिप्पणी हमें सूचित करती है।

• अप्रचलित टिप्पणियाँ - टिप्पणियाँ जिन्हें अनिवार्य माना जाता है (उदाहरण के लिए 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;
  */
  

  यह दृष्टिकोण एक बार उचित था, लेकिन संस्करण नियंत्रण प्रणाली (उदाहरण के लिए, गिट) के आगमन के साथ, यह एक अनावश्यक अव्यवस्था और कोड की जटिलता बन गई।

• ग्रन्थकारिता टिप्पणियाँ - टिप्पणियाँ जिनका उद्देश्य कोड लिखने वाले व्यक्ति को इंगित करना है, ताकि आप उनसे संपर्क कर सकें और चर्चा कर सकें कि कैसे, क्या और क्यों, उदाहरण के लिए:

  
  * @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. टिप्पणियों को उनके द्वारा वर्णित कोड के करीब रखें।

अंत में, मैं अभी भी आपको याद दिलाना चाहता हूं कि सबसे अच्छी टिप्पणी कोई टिप्पणी नहीं है, बल्कि आपके पूरे आवेदन में कुशल नामकरण का उपयोग है। एक नियम के रूप में, अधिकांश समय हम मौजूदा कोड के साथ काम करेंगे, उसे बनाए रखेंगे और उसका विस्तार करेंगे। यह अधिक सुविधाजनक है जब यह कोड पढ़ने और समझने में आसान हो, क्योंकि खराब कोड एक बाधा है। यह काम में एक रिंच फेंकने जैसा है, और जल्दबाजी इसका वफादार साथी है। और हमारे पास जितना अधिक खराब कोड होगा, उतना ही अधिक प्रदर्शन गिरेगा। इसका मतलब है कि हमें समय-समय पर रिफैक्टर करने की जरूरत है। लेकिन अगर शुरू से ही आप ऐसा कोड लिखने की कोशिश करते हैं जिससे अगले डेवलपर्स आपको ढूंढना और मारना नहीं चाहते हैं, तो आपको इसे बार-बार रिफैक्टर करने की आवश्यकता नहीं होगी। लेकिन यह अभी भी आवश्यक होगा, क्योंकि नई निर्भरता और कनेक्शन के साथ उत्पाद की शर्तें और आवश्यकताएं लगातार बदलती रहती हैं। खैर, मुझे लगता है कि आज मेरे लिए बस इतना ही है। इसे पढ़ने वाले सभी को धन्यवाद :)