एक मानक मानकों दस्तावेज़ बनाना

15

मैं एक नियंत्रण प्रणाली कंपनी में काम करता हूं, जहां अन्य नियंत्रण प्रणालियों के सामान के साथ प्राथमिक कार्य SCADA और PLC हैं ।

सॉफ्टवेयर विकास वास्तव में कुछ ऐसा नहीं है, जो कंपनी यहां और वहां के छोटे बिट्स के अलावा करती है, जब तक कि एक आंतरिक परियोजना प्रबंधन और मूल्यांकन प्रणाली बनाने का निर्णय नहीं था।

यह परियोजना उन लोगों द्वारा ली गई है जो मूल रूप से सॉफ्टवेयर लोगों के रूप में यहां आए थे और हम ज्यादातर जूनियर हैं।

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

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

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

इस पर एक बिंदु रखने के लिए, मेरा सवाल है: एक अच्छे कोडिंग मानकों के प्रमुख पहलू और सामग्री क्या हैं?

— फेलिक्स वियर
स्रोत

2

क्या आपके पास पहले से ही व्यापक परीक्षण कवरेज है? कोई फर्क नहीं पड़ता कि कोड कितना सुंदर है अगर यह गलत है ...

— JBRWilkinson

2

अच्छी बात यह है कि हम अपने सामान का परीक्षण करते हैं, हमारे पास हमारी परियोजना के लिए नियमित इकाई परीक्षण है, और रिलीज से पहले हम यादृच्छिक हॉलवे परीक्षण का उपयोग करेंगे, और काले और सफेद बॉक्स परीक्षण के लिए एक परीक्षण युक्ति लिखेंगे।

— फेलिक्स वियर

हमारे छोटे समूह की प्राथमिकता हमारी कोड मजबूत है और इसे तोड़ा नहीं जा सकता। हम बग ट्रैकिंग के लिए बगज़िला और उपयोगकर्ताओं के लिए एक कस्टम बग रिपोर्टिंग टूल का भी उपयोग करते हैं।

— फेलिक्स वियर

इस विषय पर "क्लासिक" कार्यों पर विचार किए जाने वाले कुछ संसाधन हैं। मैं इन मानकों का सबसे अच्छा हिस्सा लेने का सुझाव दूंगा जो आपके समूह की जरूरतों को पूरा करता है: 1. बेल लैब्स, इंडियन हिल सी स्टाइल एंड कोडिंग स्टैंडर्ड्स, 19 फरवरी 1997, maultech.com/chrislott/resources/cstyle/indhill-cstyle .pdf 2. स्टेलमैन, रिचर्ड, जीएनयू कोडिंग मानक, 30 जून 2012, gnu.org/prep/standards/standards.html 3. जेट प्रोपल्शन लेबोरेटरी, जे प्रोग्रामिंग के लिए जेपीएल इंस्टीट्यूशनल कोडिंग स्टैंडर्ड, संस्करण 1.0, 3 मार्च 2009, lars-lab.jpl.nasa.gov/JPL_Coding_Standard_

— विलियम लीरा

24

एक अच्छे कोडिंग मानकों के प्रमुख पहलू और सामग्री क्या हैं?

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

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

चूंकि आप स्टाइलकॉप के बारे में बात कर रहे हैं, मुझे लगता है कि आवेदन .NET फ्रेमवर्क भाषाओं में से एक में लिखा गया है।

उस स्थिति में, जब तक कि आपके पास अलग-अलग तरीके से करने के गंभीर कारण नहीं हैं, बस Microsoft के दिशानिर्देशों के साथ रहें। ऐसा करने में कई फायदे हैं, बल्कि फिर अपने स्वयं के मानकों का निर्माण करना है। पिछले चार अंक लेना:

आपको अपने स्वयं के मानकों को फिट करने के लिए स्टाइलकॉप नियमों को फिर से लिखने की आवश्यकता नहीं है। मैं नहीं कहता कि अपने नियम लिखना कठिन है, लेकिन यदि आप इसे करने से बच सकते हैं, तो इसका मतलब है कि आपके पास इसके बजाय कुछ उपयोगी काम करने में अधिक समय है।
Microsoft के दिशानिर्देश बहुत अच्छे हैं। संभावना है कि यदि आप उनमें से कुछ से असहमत हैं, तो यह हो सकता है क्योंकि आप उन्हें नहीं समझते हैं। यह वास्तव में मेरा मामला था; जब मैंने C # विकास शुरू किया, तो मुझे कुछ नियम पूरी तरह से गूंगे लगे। अब, मैं उनसे पूरी तरह सहमत हूं, क्योंकि मैं आखिरकार समझ गया कि उन्हें इस तरह क्यों लिखा गया है।
Microsoft के दिशानिर्देश अच्छी तरह से प्रलेखित हैं, इसलिए आपको अपना स्वयं का दस्तावेज़ नहीं लिखना है।
नए डेवलपर्स जो आपकी कंपनी में काम पर रखे जाएंगे, वे पहले से ही माइक्रोसॉफ के कोडिंग मानकों से परिचित हो सकते हैं। कुछ संभावनाएं हैं कि कोई भी आपके आंतरिक कोडिंग शैली से परिचित नहीं होगा।

— आर्सेनी मूरज़ेंको
स्रोत

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

— फेलिक्स वियर

BTW, आप "उपकरण जो स्वचालित जाँच सक्षम करते हैं" का उल्लेख करते हैं, ये कौन से उपकरण हैं? मैं उत्सुक हूँ।

— फेलिक्स वियर

@FelixWeir: .NET फ्रेमवर्क के लिए? StyleCop।

— आर्सेनी मोरज़ेंको

ओह ठीक है, मैंने सोचा था कि तुम कुछ और पर इशारा कर रहे थे। हम स्टाइलकॉप का उपयोग करते हैं ...: ^)

— फेलिक्स वियर

1

@FelixWeir: भी, (यदि आपने पहले ही ऐसा नहीं किया है तो) कोड विश्लेषण का प्रयास करें। उद्देश्य अलग है और शैली से संबंधित नहीं है, लेकिन यह मानकीकरण को भी सक्षम बनाता है।

— आर्सेनी मौरज़ेंको

8

ध्यान देने वाली पहली महत्वपूर्ण बात यह है कि एक कोडिंग मानकों का दस्तावेज़ सही और गलत के बारे में नहीं है। यह अच्छे और बुरे के बारे में नहीं है या कौन सा तरीका बेहतर है।

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

यह सब एकरूपता के बारे में है, और "सही और गलत" के बारे में कुछ भी नहीं है

कुछ बातों को ध्यान में रखते हुए आपको कोडिंग मानकों के दस्तावेज में स्पष्ट करना चाहिए:

नामकरण की परंपरा

आप अपने तरीकों, चर, वर्गों और इंटरफेस का नाम कैसे देंगे? आप किस संकेतन का उपयोग कर रहे हैं?

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

खरोज

आप इंडेंटेशन के लिए क्या इस्तेमाल करेंगे? एक एकल टैब? 3 रिक्त स्थान?

ख़ाका

क्या उद्घाटन विधि लाइन के रूप में ब्रेसिज़ को उसी लाइन पर रखा जाएगा? (आम तौर पर जावा) या अगली पंक्ति या स्वयं की एक पंक्ति पर? (आम तौर पर C #)

अपवाद हैंडलिंग / लॉगिंग

अपवाद हैंडलिंग और लॉगिंग के लिए आपके मानक क्या हैं, क्या यह सब होम हो गया है या आप किसी तीसरे पक्ष के टूल का उपयोग कर रहे हैं? इसका उपयोग कैसे किया जाना चाहिए?

टिप्पणी करते हुए

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

विवरण के लिए तरीकों पर \\\ के बारे में कैसे? क्या इनका उपयोग किया जाना है? कब?

अनावरण

क्या आपके सभी तरीके और क्षेत्र संभवतम निम्नतम स्तर पर लागू हो रहे हैं?

एक महत्वपूर्ण बात यह भी ध्यान दें। एक अच्छा मानक दस्तावेज़ समीक्षा कोड की मदद करने में एक लंबा रास्ता तय कर सकता है, क्या यह इन न्यूनतम मानकों को पूरा करता है?

मैं मुश्किल से क्या इन दस्तावेजों में से एक में जा सकते हैं की सतह खरोंच है, लेकिन KISS

इसे लंबा, और उबाऊ न करें, और इसके माध्यम से प्राप्त करना असंभव है, या उन मानकों का पालन नहीं किया जाएगा, इसे सरल रखें।

— RhysW
स्रोत

1

कोडिंग मानक अक्सर, विशेष रूप से C / C ++ विकास के लिए, इसमें एक (बड़ा) खंड भी होता है जिसके बारे में आपको कौन सी भाषा का उपयोग करना चाहिए और क्यों नहीं करना चाहिए ।

— बार्ट वैन इनगेन शेनॉ

2

@BartvanIngenSchenau कोई कारण नहीं है कि आपको C ++ के लिए उनकी आवश्यकता क्यों है, या आपको अन्य भाषाओं के लिए समान अनुभागों की आवश्यकता क्यों नहीं है - आप C # या JS या .. से बाहर एक गड़बड़ कर सकते हैं। सभी भाषाओं में 'सुविधाएँ हैं जिनका दुरुपयोग किया जा सकता है'। "कैसे कोड के लिए नहीं" मिनी ट्यूटोरियल के साथ मानकों को भरने के बजाय अपने देवों को अपनी नौकरी में प्रशिक्षित करने के लिए सबसे अच्छा है।

— gbjbaanb

@ जीबीजैनब: मैं अन्य भाषाओं पर टिप्पणी नहीं कर सकता, लेकिन सी ++ में पर्याप्त अंधेरे कोने और नुकसान हैं जो गलत उपयोग से बचने के बारे में नहीं है, बल्कि लोगों को उन सुविधाओं से दूर कर रहे हैं जो सही तरीके से उपयोग करना मुश्किल है (उदाहरण के लिए, ओवरलोडिंग &&)। प्रशिक्षण अच्छा है, लेकिन कभी-कभी अपनी याददाश्त को ताज़ा करने के लिए एक अच्छा संदर्भ दस्तावेज़ रखना बेहतर होता है कि आपको ऐसा क्यों नहीं करना चाहिए।

— बार्ट वैन इनगेन शेनौ

1

@BartvanIngenSchenau मुझे लगता है कि एक कोडिंग दिशानिर्देश दस्तावेज़ में बेहतर होगा , कोडिंग मानक दस्तावेज़ नहीं

— RhysW

@RhysW: काफी साफ है। मेरा अनुभव यह है कि आम तौर पर दोनों एक दस्तावेज़ ('कोडिंग स्टैंडर्ड' शीर्षक से) में संयुक्त होते हैं, लेकिन मैं इसे दो दस्तावेज़ों में समस्या के रूप में नहीं देखता हूं।

— बार्ट वैन इनगेन शेनॉउ

6

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

उदाहरण के लिए, मुझे यह केवल एक मिला: http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

वैसे भी, अपनी लौ फेंकने वाला काम संभाल कर रखें।

चीयर्स,

— मिलोज क्रजेवस्की
स्रोत

2

+1 मैं वही बात कहने जा रहा था। कोडिंग मानकों का दस्तावेज़ बनाना एक बहुत बड़ा काम है जो पहले किया जा चुका है। एक अच्छा खोजें, फिर अनुकूलित करने के लिए संशोधन करें।

— जॉन मैकइंटायर

4

मैं अधिकांश मानकों के दस्तावेजों से नफरत करता हूं क्योंकि वे आमतौर पर छोटे सामान को पसीना देने और बड़ी तस्वीर को अनदेखा करने की कोशिश करते हैं।

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

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

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

कोड कलाकृतियों को भी मौजूद होना चाहिए, इसलिए आपको यह कहने की आवश्यकता है कि क्या अपेक्षित त्रुटि हैंडलिंग अपवाद या त्रुटि कोड है - अर्थात। दस्तावेज़ वास्तु कार्यक्षमता जो उपयोग में है । यह भी कहना चाहिए कि किस प्रकार के लॉगिंग का उपयोग करना है और उपयोगकर्ता को लॉग्स / एरर हैंडलिंग को कैसे प्रस्तुत करना है या जंगल में कोड को प्रबंधित करने के लिए जो भी सबसिस्टम का उपयोग किया जाता है। मैंने एक ऐसी जगह पर काम किया जहाँ हर प्रोजेक्ट अलग तरह से लॉग-इन करता था - यह दयनीय था कि कैसे प्रत्येक कोड रिलीज़ का अपना, अलग-अलग, ऑपरेशंस डॉक्यूमेंट होता है जिसमें ऑप्स लोग बताते हैं कि कैसे गलत हुआ था। इवेंट लॉग, लॉग फ़ाइल (जिस स्थिति में), आदि सभी यहाँ मान्य हैं। कोड के लिए अन्य सामान्य पहलुओं पर भी यही लागू होता है - इसे कॉन्फ़िगर कैसे करें (कुछ कार्यक्रमों के लिए एक .config फ़ाइल का उपयोग करके कोई बिंदु, या एक कस्टम DB, या कमांड लाइन params, या दूसरों के लिए रजिस्ट्री)।

संक्षेप में, केवल एक चीज जो मायने रखती है वह है संगति । और विशाल मानकों के दस्तावेज पढ़ने और याद रखने के लिए बहुत अधिक हैं, मैं केवल उन सामानों के बारे में लोगों को सूचित करना पसंद करता हूं जो वे नहीं देख सकते हैं (जैसे कि लॉगिंग जैसे वास्तुशिल्प मानक) और उन्हें कोड रखने के लिए कहें जो वे वर्तमान में वहां मौजूद हैं। और अगर आपके पास पहले से ही कोड नहीं है, तो आपको एक मानक दस्तावेज़ की आवश्यकता नहीं है! (ठीक है, तब तक नहीं जब तक कि आपने इसे उपयोगी बनाने के लिए पर्याप्त नहीं लिखा हो)।

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

— gbjbaanb
स्रोत

2

नहीं, यह समय और ऊर्जा की पूरी बर्बादी है। StyleCop बहुत अच्छा है और वर्षों से लोगों द्वारा स्थापित किया गया था और आपकी टीम पर आपकी या किसी की तुलना में अधिक अनुभवी है। गले लगाओ और प्यार करो! यह आपको लगातार मार्गदर्शन करता है, जो किसी ऐसे दस्तावेज़ की तुलना में बेहतर है जो किसी ऐसे व्यक्ति की प्रतीक्षा कर रहा है जिसे इसे पढ़ने के लिए परेशान किया जा सकता है।

— मार्टिन मात
स्रोत