"I", "हम", या न ही कोड प्रलेखन में

Question

मैं अपने आप को (उम्मीद है कि टाइप के दस्तावेज़ीकरण) (C ++) में सहायक टिप्पणियाँ लिख रहा हूँ:

The reason we are doing this is...

"मैं" के बजाय "हम" का उपयोग करने का कारण यह है क्योंकि मैं बहुत सारे अकादमिक लेखन करता हूं जहां "हम" को अक्सर पसंद किया जाता है।

तो यहाँ सवाल है। दस्तावेज़ीकरण कोड में एक दूसरे पर पसंद करने का एक अच्छा कारण है:

1. "हम" का उपयोग करें: जिस कारण से हम यह कर रहे हैं वह है ...
2. "मैं" का उपयोग करें: मैं यह कर रहा हूँ कारण है ...
3. मेरे नाम का उपयोग करें: इसका कारण [my name]यह है ...
4. निष्क्रिय आवाज: कारण यह किया गया था ...
5. न तो: ऐसा करो क्योंकि ...

मैं # 1 का चयन करता हूं क्योंकि मुझे उस तरह से लिखने की आदत है, लेकिन दस्तावेज लेखक के लिए नहीं है, यह पाठक के लिए है, इसलिए मैं सोच रहा हूं कि क्या डेवलपर नाम जोड़ने में मददगार है या यदि सिर्फ एक और चीज जोड़नी है, जिसकी आवश्यकता है कोड को बनाए रखते समय बदला जाए।

Comments

मुझे लगता है कि यह व्यक्तिगत प्राथमिकता पर है। मुझे कोई कारण नहीं दिखता है कि एक सामान्य रूप से दूसरे की तुलना में अधिक स्पष्ट क्यों होगा।

— सशर्त

कैसे के बारे में # 5: "जब मानव घटनाओं के दौरान ...";)

— मोम

"चार अंक और सात सेकंड पहले हमारे पूर्वजों ने सीखा था कि फू को कम से कम रोकना चाहिए क्योंकि हमारी सेना को NULL के साथ पार किया जाना चाहिए"

— फिलिप

अंग्रेजी पर जोर से संबंधित। ई: प्रोग्रामर हमेशा 'हम' का उपयोग क्यों करते हैं जब वास्तव में उनका अर्थ 'मैं' या 'आप' होता है? (जो, दुर्भाग्य से, बंद था)

— इज़कट

क्यों नहीं कहते This code was written like this because...? (निष्क्रिय आवाज़)

— एल्विन वोंग

Answer 1

मैं साथ जाता हूँ:

# 6। घोषणा: ...

कहने के बजाय "कारण यह किया गया था क्योंकि प्रत्येक फू में एक बार होना चाहिए", बस यह कहें कि "प्रत्येक फू में एक बार होना चाहिए"। निष्क्रिय के बजाय, कारण के एक सक्रिय कथन में टिप्पणी करें। यह आम तौर पर समग्र रूप से एक बेहतर लेखन शैली है, बेहतर कोड की प्रकृति (जो कुछ करता है) को फिट बैठता है , और the reason this was doneवाक्यांश कोई भी जानकारी नहीं जोड़ता है। यह भी आप से सामना कर रहे समस्या से बचा जाता है।

Comments

क्या आप इस बात पर थोड़ा विस्तार करेंगे कि आप ऐसा क्यों करेंगे? एक स्पष्टीकरण के बिना, यह उत्तर एक नंगे राय की तरह दिखता है, कुछ हद तक इसे दिशा-निर्देशों के साथ परस्पर विरोधी : '... राय सब बुरा नहीं है, इसलिए जब तक कि मैं "क्योंकि मैं एक विशेषज्ञ हूं" के अलावा कुछ और के साथ समर्थित है , या "क्योंकि मैंने ऐसा कहा था", या "सिर्फ इसलिए"। अपनी राय का समर्थन करने के लिए अपने विशिष्ट अनुभवों का उपयोग करें, जैसा कि ऊपर दिया गया है, या आपके द्वारा अपने दावों का समर्थन करने के लिए सबूत प्रदान करने वाले वेब या कहीं और किए गए कुछ शोधों की ओर इंगित करें ... '

— gnat

@gnat "कारण यह किया गया था" स्पष्टीकरण के लिए कुछ भी नहीं जोड़ता है। टिप्पणियों में बिंदु भर पाने के लिए बस पर्याप्त पाठ होना चाहिए और अधिक नहीं। बारीकियों, प्रस्तावना और अन्य भरण पाठ को छोड़ दें।

— डेविड हार्कस

@gnat - जब मैंने आपकी टिप्पणी देखी, तब मैंने वास्तव में और अधिक जोड़ना समाप्त कर दिया था।

— बोबसन

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

— एलन ट्यूरिंग

मैंने पढ़ा है //के रूप में becauseज्यादातर मामलों में।

— इल्मो यूरो

Answer 2

मैं न तो पसंद करता हूं, और वास्तव में उस परिचयात्मक वाक्यांश को पूरी तरह से छोड़ दूँगा और बस इस बिंदु पर पहुंचूंगा। मैं केवल "यह" कहने से बचने की कोशिश करता हूं क्योंकि यह बताने का कोई तरीका नहीं है कि क्या टिप्पणी कोड के साथ समन्वयित है। दूसरे शब्दों में, इसके बजाय:

// The reason this was done is to prevent null pointer exceptions later on.

में कहना चाहूंगा:

// Frobnicate the widget first so foo can never be null.

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

Answer 3

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

यहाँ एक नमूना है जो मुझे लगता है कि इस बिंदु को दिखाता है।

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}

Comments

साइड नोट: SanitizeDataएक लौटना चाहिए SafeComplexObject। ;)

— जॉन पूर्डी

मैं सहमत हूं, लेकिन मैं शाब्दिक (रूपक के बजाय) टिप्पणियों को पसंद करता हूं, खासकर अगर विभिन्न भाषा पृष्ठभूमि से डेवलपर्स हो सकते हैं।

— जॉन बी। लाम्बे

Answer 4

विचार करने के लिए एक और विचार एक अच्छी तरह से तैयार की गई इकाई परीक्षा होगी जो यह दर्शाती है कि वर्णनात्मक टिप्पणी लिखने के स्थान पर यह कोड क्यों काम करता है। यह टिप्पणी लिखने पर कुछ लाभ है:

1. जब कोड को बदल दिया जाता है तो टिप्पणियां हमेशा बदलती नहीं हैं जिससे बाद में भ्रम हो सकता है।

2. इकाइयां परीक्षण अनुचर को कोड के साथ खेलने का आसान तरीका देती हैं। एक नया कोडबेस सीखना बहुत आसान हो सकता है यदि आपके पास अलग-अलग इकाइयाँ हैं जिन्हें आप देख सकते हैं कि क्या बदलाव देखने को मिलेंगे।

भले ही इस एवेन्यू को आगे काम करने की आवश्यकता होती है, इकाई परीक्षण प्रलेखन का एक उत्कृष्ट रूप हो सकता है।

Answer 5

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

मैं किसी को उनके कोड को टिप्पणी करने से हतोत्साहित करने से नफरत करूंगा क्योंकि वे मामले, तनाव और उनके सर्वनाम के व्यक्ति के बारे में चिंतित हैं।

Comments

मुझे स्पष्ट करने दें: उन टिप्पणियों के लिए जो औपचारिक प्रलेखन का हिस्सा बन जाएंगी, एक अधिक औपचारिक लहजा उपयुक्त है, और "मैं" और "हम" से सबसे अच्छा बचा जाता है। इस उत्तर के साथ मेरे मन में कभी-कभी व्याख्यात्मक टिप्पणी थी, उदाहरण के लिए जब आपने कुछ ऐसा किया है जो अगले आदमी के लिए गलत होगा। उन मामलों में, जहां केवल उसी कोड आधार में काम करने वाले लोग कभी इसे देख पाएंगे, मैं कहता हूं कि जो कुछ भी करें वह आपके अर्थ को स्पष्ट रूप से बताएगा, यहां तक ​​कि यह I wrote the code this way because...या what we really need here is...। में उन मामलों में, एक स्पष्ट टिप्पणी एक सख्त शैली से ज्यादा महत्वपूर्ण है।

— जॉन एम गैंट

Answer 6

"मैं" के बजाय "हम" का उपयोग करने का कारण यह है क्योंकि मैं बहुत सारे अकादमिक लेखन करता हूं जहां "हम" को अक्सर पसंद किया जाता है।

यह एक बुरी शैली है, यहां तक ​​कि अकादमिक पत्रों के लिए भी, जब तक कि आप छिपाने की कोशिश नहीं कर रहे हैं कि वास्तव में उस सटीक बिंदु का फैसला किसने किया है।

आपके विशिष्ट प्रश्न के लिए: मैं इस तरह की टिप्पणी नहीं छोड़ता, जब तक कि यह शुरू न हो:

// TODO: clean this up, ...

या जब तक यह बहुत महत्वपूर्ण बात नहीं समझाता है, कोड से इतना स्पष्ट नहीं हो सकता है। उस स्थिति में, टिप्पणी को यथासंभव संक्षिप्त बनाएं।