कोडिंग नियम: योग्य नावांची शक्ती, चांगल्या आणि वाईट टिप्पण्या

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

बरोबर नावे

योग्य नावे कोड वाचनीयता सुधारतात, त्यामुळे कोडशी परिचित होण्यासाठी लागणारा वेळ कमी होतो, कारण जेव्हा एखाद्या पद्धतीचे नाव त्याच्या कार्यक्षमतेचे अंदाजे वर्णन करते तेव्हा पद्धत वापरणे खूप सोपे असते. कोडमधील प्रत्येक गोष्टीमध्ये नावे असतात (व्हेरिएबल्स, पद्धती, वर्ग, ऑब्जेक्ट्स, फाइल्स इ.), त्यामुळे योग्य, स्वच्छ कोड तयार करताना हा मुद्दा खूप महत्त्वाचा ठरतो. वरील आधारावर, नावाने अर्थ व्यक्त केला पाहिजे, उदाहरणार्थ, व्हेरिएबल का अस्तित्वात आहे, ते काय करते आणि ते कसे वापरले जाते. मी एकापेक्षा जास्त वेळा लक्षात घेईन की व्हेरिएबलसाठी सर्वोत्तम टिप्पणी म्हणजे त्याला चांगले नाव देणे.

टीव्ही मालिका "शेरलॉक" (2010-2017) मधून

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

इंटरफेसमध्ये सहसा कॅपिटल अक्षराने सुरू होणारी नावे असतात आणि CamelCase मध्ये लिहिलेली असतात. इंटरफेस लिहिताना, त्याला इंटरफेस म्हणून नियुक्त करण्यासाठी "I" उपसर्ग जोडणे चांगले सराव मानले जात असे (उदाहरणार्थ, IUserService), परंतु ते खूपच कुरूप आणि विचलित करणारे दिसते. अशा परिस्थितीत, उपसर्ग (UserService) वगळणे आणि त्याच्या अंमलबजावणीच्या नावाला (उदा. UserServiceImpl) प्रत्यय म्हणून "Impl" जोडणे चांगले. किंवा शक्यतो, शेवटचा उपाय म्हणून, अंमलबजावणीच्या नावावर "C" उपसर्ग जोडा (उदा. CUserService).

वर्गांची नावे

इंटरफेसप्रमाणेच, वर्गाची नावे कॅपिटल केलेली आहेत आणि CamelCase वापरतात. आपण एखाद्या झोम्बी सर्वनाशाचा सामना करत असलो तरी काही फरक पडत नाही, शेवट जवळ आला असला तरी काही फरक पडत नाही — कधीही, कधीही, कधीही वर्गाचे नाव क्रियापद असू नये! वर्ग आणि ऑब्जेक्टची नावे संज्ञा किंवा संयुग संज्ञा (UserController, UserDetails, UserAccount इ.) असणे आवश्यक आहे. तुम्ही प्रत्येक वर्गाच्या नावाच्या शेवटी ऍप्लिकेशनचे संक्षेप टाकू नये, कारण त्यामुळे केवळ अनावश्यक गुंतागुंत निर्माण होईल. उदाहरणार्थ, आमच्याकडे वापरकर्ता डेटा मायग्रेशन ऍप्लिकेशन असल्यास, कृपया प्रत्येक वर्गात "UDM" जोडू नका, म्हणजे UDMUserDetails, UDMUserAccount, UDMUserController.

पद्धतींची नावे

सहसा, पद्धतीची नावे लहान अक्षराने सुरू होतात, परंतु ते उंट केस शैली (camelCase) देखील वापरतात. वर, आम्ही म्हटले आहे की वर्गाची नावे कधीही क्रियापद असू नयेत. येथे परिस्थिती अगदी उलट आहे: पद्धतींची नावे क्रियापदे किंवा क्रियापद वाक्ये असावीत: findUserById, findAllUsers, createUser इ. एक पद्धत (तसेच चल आणि वर्ग) तयार करताना, गोंधळ टाळण्यासाठी सुसंगत नामकरण पद्धती वापरा. उदाहरणार्थ, वापरकर्ता शोधण्यासाठी, एखाद्या पद्धतीला getUserById किंवा findUserById असे नाव दिले जाऊ शकते. आणि आणखी एक गोष्ट: पद्धतींच्या नावांमध्ये विनोद वापरू नका, कारण इतरांना विनोद समजू शकत नाही. परिणामी, पद्धत काय करते हे समजण्यात ते अयशस्वी होऊ शकतात.

परिवर्तनीय नावे

बर्‍याच प्रकरणांमध्ये, व्हेरिएबलची नावे लोअरकेस अक्षराने सुरू होतात आणि कॅमलकेस देखील वापरतात, जेव्हा व्हेरिएबल जागतिक स्थिरांक असतो. अशा परिस्थितीत, नावाची सर्व अक्षरे मोठ्या अक्षरात लिहिली जातात आणि शब्द अंडरस्कोर ("_") द्वारे वेगळे केले जातात. सोयीसाठी, व्हेरिएबल्सचे नाव देताना तुम्ही अर्थपूर्ण संदर्भ वापरू शकता. दुसऱ्या शब्दांत, जेव्हा व्हेरिएबल मोठ्या गोष्टीचा भाग म्हणून अस्तित्वात असते, उदाहरणार्थ, firstName, lastName, किंवा status. अशा प्रकरणांमध्ये, तुम्ही एक उपसर्ग जोडू शकता जे हे व्हेरिएबल कोणत्या ऑब्जेक्टशी संबंधित आहे हे सूचित करते. उदाहरणार्थ: 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 या शब्दाची आवश्यकता का आहे? हे खरोखर एक तारीख ऑब्जेक्ट असू शकते? नक्कीच नाही. तर, आम्ही फक्त firstName वापरतो. मला बुलियन व्हेरिएबल्सचा देखील उल्लेख करायचा आहे. उदाहरण म्हणून, flagDeleted नावाचे बुलियन घ्या. ध्वज या शब्दाला काही अर्थ नाही. त्याला isDeleted म्हणणे अधिक वाजवी आहे.

डिसइन्फॉर्मेशन

मी चुकीच्या नामकरण पद्धतींबद्दल काही शब्द सांगू इच्छितो. समजा आमच्याकडे 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 चे वर्णन करणाऱ्या टिप्पण्या. कदाचित सर्वात उपयुक्त टिप्पण्या आहेत, कारण दस्तऐवजीकरण 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. टिप्पण्या त्यांनी वर्णन केलेल्या कोडच्या जवळ ठेवा.

शेवटी, मी तुम्हाला अजूनही आठवण करून देऊ इच्छितो की सर्वोत्तम टिप्पणी ही कोणतीही टिप्पणी नाही, तर तुमच्या संपूर्ण अनुप्रयोगामध्ये कुशल नामकरणाचा वापर आहे. नियमानुसार, बहुतेक वेळा आम्ही विद्यमान कोडसह कार्य करू, त्याची देखभाल आणि विस्तार करू. जेव्हा हा कोड वाचण्यास आणि समजण्यास सोपा असतो तेव्हा ते अधिक सोयीचे असते, कारण खराब कोड एक अडथळा आहे. हे कामात पाना टाकण्यासारखे आहे आणि घाई हा त्याचा विश्वासू साथीदार आहे. आणि आमच्याकडे जितका वाईट कोड असेल तितकी कामगिरी कमी होते. याचा अर्थ आपल्याला वेळोवेळी रिफॅक्टर करणे आवश्यक आहे. परंतु जर तुम्ही सुरुवातीपासूनच कोड लिहिण्याचा प्रयत्न केला ज्यामुळे पुढील डेव्हलपर तुम्हाला शोधून मारून टाकू इच्छित नसतील, तर तुम्हाला ते वारंवार रिफॅक्टर करण्याची गरज भासणार नाही. परंतु तरीही ते आवश्यक असेल, कारण नवीन अवलंबित्व आणि कनेक्शनच्या जोडणीसह उत्पादनाच्या परिस्थिती आणि आवश्यकता सतत बदलत असतात. बरं, मला वाटतं आज माझ्यासाठी एवढंच आहे. आतापर्यंत वाचलेल्या प्रत्येकाचे आभार :)