अनुशंसित पढ़ने: Clean Code रॉबर्ट सी मार्टिन द्वारा।
संक्षेप में, आप चाहिए
- उपयोग सार्थक चर/विधि/वर्ग के नाम,
- अपने कार्य/तरीकों कम रखने,
- प्रत्येक वर्ग और विधि केवल एक काम करते हैं,
- है प्रत्येक विधि में कोड abstraction के एक ही स्तर पर हो।
if कथन से भी मामूली जटिल अभिव्यक्तियों को निकालने का डर न करें; जो एक को पढ़ने के लिए स्पष्ट है, इस
if (i >= 0 && (v.size() < u || d == e)) ...
या
if (foundNewLocalMaximum()) ...
(पहले कोड स्निपेट में किसी भी अर्थ खोजने की कोशिश मत करो, मैं सिर्फ यह बना :-)
स्वच्छ कोड में टिप्पणियां लगभग कभी जरूरी नहीं हैं। एकमात्र अपवाद जो मैं सोच सकता हूं वह यह है कि यदि आप कुछ अस्पष्ट भाषा सुविधा (उदा। सी ++ टेम्पलेट मेटाप्रोग्रामिंग) या एल्गोरिदम का उपयोग कर रहे हैं, और आप विधि/एल्गोरिदम के स्रोत और इसके कार्यान्वयन विवरण को एक टिप्पणी में संदर्भ देते हैं।
मुख्य कारण यह है कि किसी अन्य प्रकार की टिप्पणियां लंबे समय तक बहुत उपयोगी नहीं होती हैं, यह कोड बदलता है, और टिप्पणियां संबंधित कोड में परिवर्तनों के साथ अद्यतन नहीं होती हैं। तो थोड़ी देर के बाद टिप्पणी केवल बेकार नहीं है, लेकिन यह भ्रामक है: यह आपको कुछ बताता है (कार्यान्वयन नोट्स, डिज़ाइन विकल्पों के बारे में तर्क, बग फिक्स इत्यादि) जो कोड के एक संस्करण को संदर्भित करता है जो लंबे समय से चला गया है, और आपके पास है यह नहीं पता कि यह कोड के वर्तमान संस्करण के लिए अब प्रासंगिक है या नहीं।
एक और कारण है कि मुझे लगता है कि "मैंने इस समाधान को क्यों चुना है" अक्सर कोड में दस्तावेज़ीकरण के लायक नहीं है, यह है कि इस तरह की टिप्पणी का संक्षिप्त संस्करण लगभग हमेशा जैसा होगा "क्योंकि मुझे लगता है कि यह सबसे अच्छा है रास्ता ", या उदाहरण के लिए एक संदर्भ "सी ++ प्रोग्रामिंग भाषा, पृष्ठ 5.2.1", और लंबा संस्करण एक तीन-पेज निबंध होगा। मुझे लगता है कि एक अनुभवी प्रोग्रामर अक्सर देखता है और समझता है कि बिना किसी स्पष्टीकरण के कोड को इस तरह लिखा गया है, और एक नौसिखिया स्पष्टीकरण को भी समझ नहीं सकता है - यह हर किसी को कवर करने की कोशिश करने योग्य नहीं है।
अंतिम लेकिन कम से कम नहीं, आईएमओ यूनिट परीक्षण कोड टिप्पणियों की तुलना में दस्तावेज़ीकरण का हमेशा एक बेहतर तरीका है: आपके यूनिट परीक्षण कोड के बारे में आपकी समझ, धारणाओं और तर्क को काफी कुशलता से दस्तावेज करते हैं, इसके अलावा आपको उन्हें स्वचालित रूप से याद रखने के लिए याद दिलाया जाता है जब भी आप उन्हें तोड़ते हैं तो कोड के साथ सिंक करें (ठीक है, बशर्ते आप वास्तव में उन्हें अपने निर्माण के साथ चलाएं ...)।
डुप्लिकेट: http://stackoverflow.com/questions/784250/is-it-possible-to-write-good-and-understandable-code-without-any-comments – tangens
ध्यान दें कि कोड आपको कुछ नहीं बता सकता है क्यों एक विशेष तरीके से किया जाता है, केवल कैसे। –
यह एक मिथक है कि केवल टिप्पणियां "क्यों" बता सकती हैं। कभी-कभी आपको इसके लिए एक टिप्पणी की आवश्यकता होती है, लेकिन अक्सर कोड पूरी कहानी बता सकता है। देखो, एक टिप्पणी खराब नहीं है। लेकिन टिप्पणियों की एक संकेत होने की आवश्यकता पर विचार करें कि कोड, शायद, स्पष्ट किया जा सकता है। –