सख्त टाइपिंग का उपयोग करते समय डॉकब्लॉक टाइपिन बेमानी हैं

Question

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

स्थैतिक विश्लेषण के आगमन के साथ, इन टाइपिन्ट्स ने मुझे असंगतताओं और संभावित बगों को खोजने में बहुत मदद की है। हाल ही में मैंने पूरा कोडबेस (अब PHP7.2 पर चल रहा है) को सभी मापदंडों और वापसी मानों को टाइप करने के लिए परिवर्तित कर दिया है, जहां संभव हो, PHP के टाइपिन्ट्स का उपयोग करके। और अब मैं सोच रहा हूँ ... क्या ये डॉकब्लॉक टाइपहिन निरर्थक नहीं हैं? यह सभी डॉकब्लॉक को हमेशा बदलते कोड के साथ सिंक करने के लिए काफी काम करता है और चूंकि वे कोई नई जानकारी नहीं जोड़ते हैं, इसलिए मैं सोच रहा हूं कि उन्हें पूरी तरह से हटा देना बेहतर है या नहीं।

एक हाथ में, प्रलेखन हटाने से बुरा लगता है, भले ही यह बेमानी हो। दूसरे में, मुझे वास्तव में ऐसा लगता है कि डू-नॉट-रिपीट-योरसेल्फ-थ्योरी रोज़ टाइप-हिंटिंग सामान जो पहले से ही टाइप-हिंटेड है।

Comments

हटाया "मुझे कुछ राय सुनना अच्छा लगेगा।" बयान जैसा कि यह उस तरह का है जिससे एक अच्छा प्रश्न राय-आधारित के रूप में बंद हो सकता है।

— डेविड अरनो

@DavidArno: आह धन्यवाद। मैं कुछ तथ्यात्मक आधारित अंतर्दृष्टि प्राप्त करना चाहता हूँ :)

— Xatoo

Answer 1

कोड में पाई जा सकने वाली जानकारी को टिप्पणियों में डुप्लिकेट नहीं किया जाना चाहिए।

सबसे अच्छा, यह उन्हें सिंक्रनाइज़ रखने के लिए व्यर्थ प्रयास है। अधिक संभावना है, वे अंततः सिंक से बाहर निकल जाएंगे। उस बिंदु पर, वे सिर्फ भ्रमित कर रहे हैं।

यदि आप DocBlock को वैधानिक रूप से टाइप की गई भाषाओं (जैसे Java, C #) के समकक्ष देखते हैं, तो आप पाएंगे कि doc टिप्पणियों में प्रकार की जानकारी नहीं है। Insofar जैसा कि आपके PHP कोड में यह मामला है, मैं दृढ़ता से सूट का पालन करने की सलाह दूंगा। बेशक, जहां टाइपिंग को लागू नहीं किया जा सकता है, एक टिप्पणी अभी भी आपका सबसे अच्छा विकल्प है।

यह PHP के लिए प्रासंगिक नहीं है, लेकिन डुप्लिकेट प्रकार की जानकारी तब समझ में आ सकती है जब टाइप अंतर्निहित है (जैसे हास्केल)।

Answer 2

हाँ, docblocks php 7 के साथ बेमानी हो गए हैं।

कोडिंग में ज्यादातर समय पढ़ने में व्यतीत होता है, इसलिए एक ही चीज को दो बार पढ़ने से आपकी उत्पादकता प्रभावित होती है। इसके अलावा, वास्तव में महत्वपूर्ण टिप्पणियों को याद करना आसान बनाता है।

मैं छोड़कर जब मैं टाइप करने के लिए एक खास प्रकार की एक सरणी संकेत चाहते हैं, अब और docblocks नहीं लिखते (जैसे @return int[]या @param SomeStatus[] $statusList) या मैं विधि, पैरामीटर या वापसी मान के बारे में टिप्पणी जोड़ने के लिए चाहते हैं। मैंने पाया कि phpstorm निरीक्षण को ट्रिगर करना महत्वपूर्ण है जब आपके पास कोई पैरामीटर नहीं है और यदि आपके पास docblock है तो किसी डॉकब्लॉक में प्रकार वापस करें।

Answer 3

कोड और प्रलेखन में आम तौर पर अलग-अलग ऑडियंस होते हैं: प्रलेखन उस फ़ंक्शन के उपयोगकर्ताओं के लिए होता है। उन्हें प्रकार समझने के लिए कोड को नहीं देखना चाहिए। इसलिए, प्रलेखन में सभी आवश्यक जानकारी शामिल होनी चाहिए, जिसमें प्रकार शामिल हैं।

कुछ प्रणालियों में, प्रलेखन में एक पैरामीटर प्रकार निर्दिष्ट करना आवश्यक नहीं है, क्योंकि कोड से प्रकार लिया जा सकता है। PHPDoc ऐसी प्रणाली नहीं है। इसके बजाय, @paramटैग का दस्तावेजीकरण किया गया है

जब यह प्रदान किया जाता है तो यह इंगित करने के लिए एक प्रकार होता है कि क्या अपेक्षित है

"कभी-कभी बदलते कोड के साथ सभी docblocks को रखने के लिए काम का एक सा" कुछ हद तक कम हो जाता है क्योंकि PHPDoc कोड प्रकार के संकेत के खिलाफ प्रलेखन प्रकार के संकेत की जांच करेगा। यह एक प्रकार का लाइनिंग / स्थैतिक विश्लेषण है, इसलिए अपनी प्रलेखन पीढ़ी को अपनी स्वचालित परीक्षण पाइपलाइन का हिस्सा बनाएं।

एक और सवाल जो आप खुद से पूछना चाहते हैं, वह यह है कि इन कार्यों को इस विस्तार से क्यों लिखा जाता है, जब वे "कभी बदलते हैं"। सामान्य प्रेरणा आपके इंटरफेस का HTML संदर्भ मैनुअल बनाना है। लेकिन अगर डॉक्यूमेंट को कभी भी IDE के बाहर नहीं पढ़ा जाता है, या यदि आपके पास स्थिर इंटरफेस नहीं है, जहाँ डॉक्यूमेंटेशन का कोई मतलब नहीं है, तो विस्तृत डॉकब्लॉक्स अनावश्यक या भ्रामक हैं। जब तक आप एक स्थिर डिजाइन पर नहीं आ जाते हैं, तब तक केवल एक सारांश लिखना और पूर्ण डॉक्स को स्थगित करना बेहतर हो सकता है।