कोड प्रलेखन पहले? [बन्द है]

Question

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

Comments

हाँ। यह एक अच्छा विचार है। लोग ऐसा हमेशा करते हैं। आप और क्या जानना चाहते हैं?

— एस.लॉट

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

— नौकरी

यह एक महान विचार है, अन्यथा आप अनिर्दिष्ट सुविधाओं के साथ समाप्त होते हैं।

— १

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

— केनेथ

यह बेहतर होगा यदि आप स्वीकृति परीक्षण लिखे, और फिर उन स्वीकृति परीक्षणों को पूरा करने के लिए टीडीडी का उपयोग किया;)

— मार्टिन ब्लेर

Answer 1

हाँ।

यह आपको सोचता है कि वास्तव में, आपका कोड क्या करना चाहिए । विचार यह है कि आप कोड के किसी भी हिस्से से शुरू कर सकते हैं और यह जान सकते हैं कि उस मॉड्यूल को पूरा करने के लिए वास्तव में क्या करना है।

यह आईडीई की तुलना में ड्राइंग बोर्ड पर कुछ तय करना भी आसान है।

Comments

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

— कैफ़ीक्यू

@ सच है। मैंने अपना उत्तर संपादित कर दिया है।

— मैक्सएमपी

मैं असहमत हूं। पहले पूर्ण दस्तावेज़ बनाना पहले से कहीं अधिक दस्तावेज़ीकरण से भी बदतर है, यह जानने के लिए कि आगे कहाँ जाना है। परिवर्तन होता है। यह जानने का कोई तरीका नहीं है कि क्या आप सही दिशा में जा रहे हैं, और जब तक आप इसका पता लगाते हैं, आप पीछे रह जाते हैं। क्या काम करता है के साथ जाओ, इसे सुधारें और इसे ठीक करें जैसे ही आप जाते हैं, कोड को सबसे अधिक दस्तावेज होने दें।

— ज़ाचरी स्कॉट

बेशक जैसे ही आप बग को ठीक करने के लिए या किसी नई आवश्यकता को पूरा करने के लिए अपना कोड बदलते हैं, आपका दस्तावेज़ पुराना हो जाता है। निष्पादन योग्य परीक्षणों के रूप में प्रलेखन जाने का रास्ता है!

— जॉन्सवेब

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

— इवान प्लाइस

Answer 2

इसके बारे में सोचने के दो तरीके हैं:

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

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

Comments

टीडीडी के लिए +1। डॉक्यूमेंटिंग की तुलना में बिलकुल बेहतर विकल्प, फिर कोड बदलने पर डॉक्यूमेंटेशन की महत्वपूर्ण मात्रा को बदलना।

— एथेल इवांस

TDD के रूप में प्रलेखन के लिए +1 भी।

— सेवेंससीट

उत्पाद मौजूद होने से पहले आपके पास पूर्ण उत्पाद दस्तावेज़ हो सकते हैं। मैंने इसे किया है, मैंने उन परियोजनाओं में काम किया है जहाँ इसकी आवश्यकता थी। आपके पास स्क्रीनशॉट नहीं होंगे, लेकिन आपके पास सब कुछ हो सकता है (स्क्रीन पर तत्वों के स्थान का प्रतिनिधित्व करने वाले विज़ियो आरेख सहित)।

— 18'11

@jwenting मेरे पास भी है और यह आरेखों के साथ-साथ शब्द दस्तावेजों के 200+ पृष्ठों का संग्रह था। न केवल यह समय की पूरी बर्बादी थी, बल्कि इसे तैयार करने के लिए 2 महीने की आवश्यकता थी और हमारे पीएम समय की एक महत्वपूर्ण राशि को लगातार अद्यतन करने के लिए डिजाइन के रूप में अंतिम उत्पाद में विकसित हुआ। यह वास्तव में शायद बालसाल्मीक का उपयोग करके ग्राफिकल मॉकअप के साथ बहुत तेजी से चला गया है। अगली बार जब मैं एक ऐसी परियोजना पर काम करता हूँ जहाँ यह एक आवश्यकता है तो मैं एक बात करने जा रहा हूँ कि किसी अन्य व्यक्ति को इसे पूर्णकालिक रूप से प्रबंधित करने के लिए सौंपा जाना चाहिए क्योंकि इसे बनाए रखने के लिए कितना प्रयास करना पड़ता है।

— इवान प्लाइस

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

— इवान प्लाइस

Answer 3

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

"प्रलेखन पहले" पर एक भिन्नता साक्षर प्रोग्रामिंग है । प्रोग्रामर के नजरिए से कार्यक्रम क्या करेगा, इसका विवरण लिखकर शुरू करें। इसे संकलित करते रहें। वोइला, एक साक्षर कार्यक्रम।

Comments

बिल्कुल सही! परिवर्तन होता है। डॉक्यूमेंटेशन में सुधार होता है। कोड प्रलेखन का सबसे कठिन रूप है।

— ज़ाचरी स्कॉट

Answer 4

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

संपादित करें: जैसा कि आप लंबे समय तक चलते हैं, कुछ दस्तावेज होने चाहिए। इससे बाद में पूर्ण प्रलेखन करना आसान हो जाता है।

Answer 5

जोशुआ बलोच ने "कोडर्स एट वर्क" पुस्तक के लिए अपने साक्षात्कार में इस बिंदु पर चर्चा की।

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

सबसे महत्वपूर्ण बात यह जानना है कि आप क्या बनाने की कोशिश कर रहे हैं: आप किस समस्या को हल करने की कोशिश कर रहे हैं। आवश्यकताओं के विश्लेषण के महत्व को अतिरंजित नहीं किया जा सकता है। ऐसे लोग हैं जो सोचते हैं, "ओह, हाँ, आवश्यकताओं का विश्लेषण; आप अपने ग्राहक के पास जाते हैं, आप कहते हैं, 'आपको क्या चाहिए?' वह आपको बताता है, और आप काम कर रहे हैं। "

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

उपयोग के मामलों का एक अच्छा सेट के साथ आ रहा है सबसे महत्वपूर्ण बात आप इस स्तर पर कर सकते हैं। आपके पास एक बार ऐसा करने के लिए, आपके पास एक बेंचमार्क होता है जिसके खिलाफ आप किसी भी संभावित समाधान को माप सकते हैं। यह ठीक है यदि आप बहुत समय बिताते हैं, तो यह उचित रूप से सही के करीब है, क्योंकि यदि आप इसे गलत पाते हैं, तो आप पहले ही मर चुके हैं। बाकी प्रक्रिया निरर्थकता में एक अभ्यास होगी।

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

- जोशुआ बलोच, पीटर सिबेल द्वारा " कोडर्स एट वर्क: रिफ्लेक्शंस ऑन द क्राफ्ट ऑफ प्रोग्रामिंग " में एक साक्षात्कार से

यदि आप पहले से ही इन पंक्तियों के साथ सोच रहे हैं, तो अच्छा होगा यदि आप पुस्तक पर पकड़ बना सकें और पूरा साक्षात्कार पढ़ें। जैसा कि मैंने कहा, वह हमेशा बहुत ज्ञानवर्धक है।

Comments

यह अच्छी सलाह है, लेकिन अच्छे प्रलेखन में एपीआई का उपयोग शामिल है।

— फ्रैंक हिलमैन

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

— DPM

Answer 6

कुछ लोग आगे भी कहते हैं कि एक कंपनी को पूरी तरह से पीछे की ओर काम करना चाहिए, इसलिए

1. प्रेस विज्ञप्ति लिखिए
2. एक सामान्य प्रश्न लिखें
3. ग्राहक अनुभव को परिभाषित करें
4. उपयोगकर्ता पुस्तिका लिखें
5. प्रोग्रामिंग शुरू करें

Http://www.allthingsdistributed.com/2006/11/working_backwards.html देखें

Answer 7

पहले पूरा कोड प्रलेखन लिखना शायद ओवरकिल है और कुछ हद तक झरना कार्यप्रणाली की याद दिलाता है। हालाँकि, मैंने पाया है कि अधिक व्यावहारिक दृष्टिकोण पहले README लिख रहा है । यहाँ पर क्यों:

README आपकी परियोजना के प्रत्येक विवरण का दस्तावेजीकरण नहीं करता है । इसके बजाय, इसमें आम तौर पर निम्नलिखित जानकारी होती है:

1. विवरण : लघु "बिक्री पिच"। पाठक को बताएं कि उन्हें क्यों पढ़ना चाहिए।
2. त्वरित उदाहरण : विवरण का समर्थन करने के लिए लघु कोड स्निपेट या स्क्रीनशॉट।
3. त्वरित शुरुआत : कैसे प्राप्त करने के लिए, निर्देश स्थापित करें, और अधिक उदाहरण।
4. इसके अलावा प्रलेखन : पूर्ण डॉक्स और अधिक जानकारी के लिए लिंक।
5. परियोजना संगठन : लेखक कौन हैं, योगदान कैसे करें, बग कैसे दर्ज करें।
6. कानूनी नोटिस : लाइसेंस, कॉपीराइट और अन्य कानूनी विवरण।

"बिक्री की पिच" ​​को लिखने से सामने वाले को स्पष्ट हो जाता है कि यह परियोजना क्यों होनी चाहिए और डेवलपर्स को इसका उपयोग क्यों करना चाहिए। परियोजना का वर्णन करने के लिए पूर्ण वाक्य लिखने का मात्र कार्य अक्सर इसे बेहतर के लिए बदलता है: आप इसे बेहतर समझते हैं, नए विचारों को विकसित करते हैं, और संभावित समस्याओं को उजागर करते हैं। यह भी एक महान प्राथमिकता उपकरण है: "बिक्री पिच" ​​में कुछ भी एक होना चाहिए!

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

"आगे के प्रलेखन" में, मैं उन टुकड़ों की रूपरेखा तैयार करता हूं जिन्हें बाद में किए जाने के लिए विस्तृत दस्तावेज की आवश्यकता होगी। "प्रोजेक्ट संगठन" मुझे यह पता लगाने देता है कि प्रोजेक्ट और कोडिंग प्रथाओं पर कौन काम करेगा। "कानूनी नोटिस" ... अच्छी तरह से, उन लोगों को भी रास्ते से बाहर कर सकते हैं।

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

अधिक जानकारी के लिए, निम्नलिखित की जांच करें:

1. रीडमी प्रेरित विकास
2. सबसे महत्वपूर्ण कोड कोड नहीं है
3. आप वही हैं जो आप दस्तावेज़ करते हैं

Answer 8

आप इस बारे में क्यों नहीं सोचना चाहेंगे कि कक्षाएं कैसे बातचीत करती हैं? वह बुरी चीज क्यों है? मैं वास्तव में अंतर्क्रियाओं के बारे में सोचता हूं इससे पहले कि मुझे पता है कि कक्षाएं क्या हैं। इस तरह कक्षाएं खुद को पहचानती हैं।

Answer 9

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