Unlimited WordPress themes, graphics, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Web Design
  2. Documentation
Webdesign

परफेक्ट CSS डॉक्यूमेंटेशन के लिए 8 सर्वश्रेष्ठ अभ्यास

Length:LongLanguages:

Hindi (हिंदी) translation by Ashish Rampal (you can also view the original English article)

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

फिर भी CSS का डॉक्यूमेंटेशन आपके प्रोजेक्ट में बहुत कुछ दे सकता है: नई टीम के सदस्यों के ऑनबोर्डिंग को आसान बनाने के लिए बेहतर कोड प्रैक्टिस को प्रोत्साहित करने से। इस अनुच्छेद में मैं CSS के दस्तावेज के लाभों को समझाऊंगा और Bitovi में मेरी टीम और मैं क्या आपके लिए डॉक्यूमेंटेशन कार्य करने के लिए सबसे अच्छा अभ्यास माना जाता है, न कि अन्य तरीकों के आसपास। चलो इसमें घुसें।

1. ग्राउंड नियम सेट करें

यह डॉक्यूमेंटेशन गाड़ी में सवार हो जाना मुश्किल है जब यह आपके और आपकी टीम को स्पष्ट नहीं करता है कि क्या दस्तावेज़ करना है या आप इसे कैसे काम करना चाहते हैं। तो पहला कदम यह है कि आप किस कन्वेंशन का उपयोग करेंगे और आपको उन्हें कैसे लागू करना चाहिए। आप ऐसा एक लाइव दस्तावेज़ में कर सकते हैं ताकि टीम में सभी योगदान कर सकें। इस तरह, आपका दृष्टिकोण बदलता है या अधिक व्यापक हो जाता है, आप इसे up-to-date रख सकते हैं। एक शेयर्ड Google दस्तावेज़, आपके कोड रेपो पर एक wiki page, या ("इससे भी बेहतर") आपके "लाइव स्टाइल गाइड" पर एक page सभी बेहतरीन स्थान हैं।

अब आइए वास्तविक "जमीन नियमों" पर गौर करें जो आप शामिल कर सकते हैं।

2. अपने कोड बेस की संरचना समझाओ

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

यहां एक उदाहरण है:

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

एक अन्य महत्वपूर्ण तत्व यह बताता है कि जहां नई स्टाइल शामिल की जानी चाहिए और जिस भी कदम का पालन करना चाहिए। उपर्युक्त उदाहरण यह दर्शाता है, लेकिन CSS की विरासत प्रकृति को देखते हुए, यह विस्तार से वर्णन करने के लिए उपयुक्त हो सकता है।

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

सिनेरियो #1

यदि आप बूटस्ट्रैप द्वारा निर्धारित स्टाइल को ओवरराइट करना चाहते हैं, तो:

  1. पता करें कि बूटस्ट्रैप फ्रेमवर्क के स्टाइलशीट में नियम किस प्रकार परिभाषित है।
  2. "src/styles/bootstrap-custom" पर जाएं
  3. वही स्टाइलशीट खोजें
  4. यदि यह अस्तित्व में नहीं है, तो उसी नाम के साथ उस डायरेक्टरी में एक नया बनाएं।
  5. अपने ओवरराईट करें और किसी भी महत्वपुर्ण चीज को पॉइंट आउट करें।
  6. अन्त में, "src/styles/style.less" में नया स्टाइलशीट आयात करें।

सिनेरियो  #2

यदि आप एक नयी स्टाइल परिभाषा जोड़ना चाहते हैं जो कि बूटस्ट्रैप को ओवरराइट नहीं कर रहा है और यह एप्लिकेशन में कहीं भी उपलब्ध होना चाहिए, तब:

  1. "src/styles/custom" पर जाएं।
  2. एक स्टाइलशीट ढूंढें जहां नई स्टाइल को जोड़ा जा सकता है (सोचें: क्या यह एक बटन को परिभाषित करने के लिए एक स्टाइल है, या क्या यह एक मिक्सिन की तरह पुन: प्रयोग योग्य स्टाइल है?) और इसे जगह दें जहां यह सबसे अधिक समझ में आता है।
  3. यदि कोई स्टाइलशीट नहीं है, जहां यह नई स्टाइल डालना समझ में आता है, तो एक नया बनाएं।
  4. इसे हमारे नेमिंग कन्वेंशन के हिसाब से नाम दें।
  5. अपनी नई स्टाइल जोड़ें और महत्व के बारे में पॉइंट आउट करें।
  6. अन्त में, "src/styles/style.less" में नया स्टाइलशीट इम्पोर्ट करें।

सिनेरियो #3

यदि आप एक कॉम्पोनेन्ट के लिए एक नई स्टाइल परिभाषा जोड़ना चाहते हैं (इसका मतलब यह है कि केवल उस कॉम्पोनेन्ट के लिए उपलब्ध होगा, जहां कॉम्पोनेन्ट एप्लीकेशन में उपयोग किया जाता है), तो:

  1. "src/components" पर जाएं।
  2. उस कॉम्पोनेन्ट को ढूंढें जिसे आप स्टाइल में करना चाहते हैं।
  3. कॉम्पोनेन्ट डायरेक्टरी के अंदर, कॉम्पोनेन्ट के लिए स्टाइलशीट खोजें।
  4. अंत में, नई स्टाइल जोड़ें और किसी भी महत्वपूर्ण की ओर पॉइंट आउट करें।

यह गाइड:

  • हमारे स्टाइल्स को संगठित रखने के लिए सर्व करें।
  • हमारे स्थापित इनहेरिटेंस के अनुसार काम करने वाली स्टाइल्स को रखें क्योंकि सही जगहों पर ओवरराइट किया जा सकें।
  • अतिसंवेदनशील नियमों को लिखने वाले डेवलपर्स से बचें।
  • गैर-इरादा एलिमेंट्स के लिए लीक की गई स्टाइल्स से बचें।

3. अपने कोडिंग मानकों की स्थापना

आपके कोडिंग मानकों या CSS स्टाइल गाइड, जिस प्रकार से आपकी टीम ने CSS लिखने पर सहमति व्यक्त की है इसमें कोड लिखने के सर्वोत्तम प्रथाएं शामिल हैं, जैसे फोर्मत्तिंग, नेमिंग और सिंटेक्स कन्वेंशन। कई कम्पनियों ने शेयर किया है जिस तरह से वे करते हैं (CSS-Tricks के इस आलेख में एक महान संकलन है: CSS स्टाइल गाइड्स)। इस तरह की जानकारी साझा करने के लिए यहां कुछ तरीके हैंI

न करें बनाम करें की सूची

एक व्यावहारिक विकल्प उपलब्ध कराने के दौरान, जिस चीज से आप बचाना चाहते हैं, उसे इंगित करने के लिए इस प्रारूप का उपयोग करें। यह अस्पष्टता को निकालता है और लोगों को एक विशिष्ट चीज़ करने के लिए प्रोत्साहित करता है उदाहरण के लिए:

क्या न करें
क्या करें
इंडेंटेशन के लिए टैब का उपयोग न करें।
इंडेंटेशन के लिए चार (4) रिक्त स्थान का उपयोग करें।
अंडर_स्कोर या "कैमल कैस" नाम क्लासेज या ID के लिए उपयोग न करें।
शब्दों को अलग करने के लिए डैश का उपयोग करें।
अंतर्निहित मार्कअप संरचना को प्रतिबिंबित करने के लिए Class और ID नामों का उपयोग न करें। .container-span और .small-header-div खराब नाम हैंI

ऑब्जेक्ट्स के संदर्भ में CSS के बारे में सोचें और नामों के रूप में साधारण संज्ञा का उपयोग करें। .global-alert और .badge अच्छे नाम हैंI

ID और अति विशिष्ट-स्पेसिफिक चयनकर्ताओं को स्टाइल में न लें। केवल जब यह ज़रूरी हो तभी इनका प्रयोग करें (उदा. form कंट्रोल्स या page एंकर)।
पुन: प्रयोग को सुविधाजनक बनाने और CSS चयनकर्ता विशिष्टता संघर्ष को कम करने के लिए क्लासेज का उपयोग करें।

सर्वश्रेष्ठ अभ्यास सूची

अपने दिशानिर्देशों को सर्वोत्तम प्रथाओं में संक्षेप करें और उदाहरणों में शामिल करें। इससे प्रत्येक को पढ़ना और समझना आसान होगा। उदाहरण के लिए:

उत्तम व्यवहार उदाहरण
कई चयनकर्ताओं को अलग-अलग लाइनों पर लिखें। .btn,
.btn-link {
}
चयनकर्ता और ओपनिंग ब्रेस के बीच एक स्थान शामिल करें। .selector {
}
जब संभव हो hex वैल्यूज के लिए शार्टहैंड का उपयोग करें #fff बनाम #ffffff
लोवरकेस में hex वैल्यू लिखें #3d3d3d vs #3D3D3D
सिंगल कोट्स में URL संलग्न करें। आम तौर पर, सिंगल कोट्स को डबल कोट्स के ऊपर पसंद किया जाता है, क्योंकि वे टाइप करना आसान है। url('/image.png') vs url("/image.png")
एंगल्स (डिग्री) और समय (s या ms) को छोड़कर, शून्य (0) मूल्यों के लिए इकाइयों का उपयोग न करें।
margin-right: 0; vs margin-right: 0px;

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

मैंने एक परियोजना पर काम किया जहां हमने यह हमारे लिविंग स्टाइल गाइड में शामिल किया था। कोड के एक भाग के रूप में, हमने इन सर्वोत्तम तरीकों को रेपो के लिए प्रतिबद्ध और धक्का दिया। फिर यह सुनिश्चित करने के लिए कि सभी बोर्ड पर थे, टीम में सभी को पुल रिक्वेस्ट को स्वीकृति देने से पहले इसे विलयस(merge) कर सकते थे। यह गारंटी है कि सभी को रीव्यू और डिसकस करने के लिए समय देना होगा।

4. लम्बी स्टाइलशीट्स से बचें

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

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

एक लंबी फाइल में, एक लम्बा इंडेक्स...

फाइल को तोड़ना, कोई भी इंडेक्स जरूरी नहीं है:

बड़े एप्लीकेशन में काम करने पर विचार करने के लिए एक अन्य उदाहरण है modlet workflow। यह बताता है कि कंपोनेंट्स द्वारा संगठित छोटी फ़ाइलों के साथ काम करने से आपके ऐप में और आसानी से उन्हें परीक्षण करने और संयोजन करने की सुविधा मिलती है।

5. CSS को डॉक्यूमेंट करें स्टाइल गाइड को ध्यान में रख कर

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

यह वह जगह है जहां CSS को एक स्टाइल गाइड के साथ दिमाग का डोक्युमेंटिंग करना आता है। इसके पीछे का विचार यह है कि एक स्टाइल गाइड आपको अपने CSS के लिए एक अच्छी संरचना निर्धारित करने में मदद कर सकता है क्योंकि यह बनाने के लिए आपको इसमें अंतर करने की आवश्यकता होगी:

  • बेसलाइन स्टाइल्स जो आपके ऐप्लिकेशन का लुक और फील को परिभाषित करती हैं (जिसमें आपके द्वारा उपयोग किये जा रहे कोई भी CSS फ्रेमवर्क शामिल है)
  • स्पेसिफिक कॉम्पोनेन्ट के लिए किए गए कस्टमाइज़ेशन, और
  • स्पेसिफिक पेजेज के लिए किए गए कस्टमाइज़ेशन

आपके CSS का बल्क बेसलाइन स्टाइल्स में शामिल होना चाहिए, क्योंकि वे एप्लीकेशन में कहीं भी उपलब्ध हैं और अपने डिफ़ॉल्ट स्थिति में सभी एलिमेंट्स को प्रभावित करते हैं। जैसा कि आप एक विशेष रूप और व्यवहार के साथ कंपोनेंट्स को जोड़ते हैं, या ऐसे मामलों में जहां एक एलिमेंट या किसी पेज के कॉम्पोनेन्ट के लेआउट की आवश्यकता होती है, कस्टम स्टाइल्स को होना चाहिए।

यह विशेष सेटअप आपके ऐप्लिकेशन में कैसे काम कर सकता है, यह जानने के लिए एक शानदार तरीका है कि एक साइट गाइड साइटमैप का निर्माण करना है। एक बार जब आप जानते हैं कि आपके एप्लिकेशन में स्टाइल गाइड कैसे दिखता है, तो आप उन एलिमेंट्स को ध्यान में रख सकते हैं। जिनके बारे में उदाहरण के लिए, यदि आपने अपनी स्टाइल गाइड में बटन और नेविगेशन्स कैसे दिखें यह परिभाषित किया हैं, तो यह स्पष्ट है कि आपको नए स्टाइल्स और डॉक्यूमेंटेशन ("buttons.css" और "navs.css" में) कहाँ जोड़ना चाहिए। लेकिन उस नेविगेशन का क्या जो बटन से बना है?

स्टाइल गाइड रखने से आपको यह निर्णय लेने में मदद मिल सकती है, क्योंकि आप तुलना कर सकते हैं कि एक डिस्प्ले और एक मार्कअप परस्पेसिटवे से बटन और नेविगेशन्स कैसे दिखते हैं। इस उदाहरण को देखें:

इस स्थिति में, CSS के लिए दो संभावित स्थान हैं जो बटन से बने नेविगेशन है:

  1. यदि मार्कअप अन्य नेविगेशन की संरचना का अनुसरण करता है, लिंक की एक सूची का उपयोग करके, या <nav> लिंक के साथ जो बटन की तरह दिखाई देता है, तो "navs.css" में nav स्टाइल जोड़ें।
  2. यदि आपके द्वारा उपयोग किए जाने वाले मार्कअप <button> है, तो स्टाइल्स को "buttons.css" में जोड़ें। आप इसे एक अलग स्टाइलशीट के रूप में भी जोड़ सकते हैं (जैसे "buttons-group.css")। इस स्थिति में, "navigation" शब्द किसी भी समय उपयुक्त नहीं होगा क्योंकि HTML बटन नेविगेशनल आइटम के रूप में कम सुलभ हैं।

6. अपनी स्टाइलशीट्स को सेक्शंस बाँट दें

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

आरंभ करने के लिए, प्रत्येक स्टाइलशीट को कम से कम एक शीर्षक और (जब उपयोगी होता है) एक संक्षिप्त विवरण शामिल करना चाहिए। टाइटल फ़ाइल के नाम जितना ही आसान हो सकता है, टाइटल की तरह दिखने के लिए कैपिटलाइज़ (उदाहरण: "Buttons" स्टाइलशीट "buttons.css" के लिए), या यह फाइल के नाम के सामान ही हो सकते हैं, जैसे यह:

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

इसके अलावा, ध्यान दें कि मैंने जिस कमेंट स्टाइल का उपयोग किया था वह /** बनाम बस /* के साथ खुलता है। ये एक ऐसा कन्वेंशन है जो JSDoc में कमैंट्स को पार्स करने के लिए प्रयोग किया जाता है, जिन्हें ऑटो-जनरेटेड डॉक्यूमेंटेशन में शामिल किया जाना चाहिए। मैं इस स्टाइल का उपयोग करने की सलाह देता हूं, क्योंकि कई जीवित स्टाइल गाइड जेनरेटर JSDoc प्रारूप का उपयोग करते हैं, इसलिए जब आप जनरेटर का उपयोग करने के लिए तैयार हों, तो आपके कोड को बहुत कम अतिरिक्त काम की आवश्यकता होगी।

किसी भी मामले में, आप किसी सेक्शन को दर्शाने के लिए अन्य स्टाइल्स का उपयोग कर सकते हैं जैसे कि:

कुछ हद तक, यह इस बात पर निर्भर करता है कि आपकी टीम किस बात से सहमत है, यह एक सेक्शन बनाने का सबसे अच्छा तरीका है। एकमात्र आवश्यकता /* शुरुआत में और */ अंत में उपयोग करना है। वास्तव में क्या मायने रखता है कि जो भी दृष्टिकोण आप उपयोग करते हैं, आप इस पर स्टिक रहते हैं और इसे अपने CSS कोड में एक कंसिस्टेंट तरीके से उपयोग करते हैं।

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

ऐसा करने से यह एक सेक्शन के विचार को मजबूत करेगा। इसके अलावा, डिस्क्रिप्शन को कई लाइनों में तोड़ने का प्रयास करें (हैरी रॉबर्ट्स ने 80 अक्षरों की सिफारिश की है) ताकि कई फाइलें खोलने या Github पर इसे पढ़ते समय पढ़ना आसान हो।

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

आइए इस तुलनात्मक उदाहरण को देखें। सबसे पहले, बिना किसी सेक्शन के LESS कोड ब्लॉक:

और सेक्शंस के साथ वही कोड ब्लॉक:

7. अपने स्टाइलशीट्स के कंटेंट्स को इंडेक्स करें

यह स्टाइलशीट में जो कुछ है, उसका एक स्नैपशॉट प्रदान करने का एक शानदार तरीका है और उन परियोजनाओं में जरूरी है, जहां किसी कारण के लिए, लंबे स्टाइलशीट हैं (उन परियोजनाओं के प्रशंसक नहीं हैं, लेकिन ऐसा होता है!)।

एक स्टाइलशीट इंडेक्स आमतौर पर इस तरह दिखता है:

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

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

8. डोक्युमेंटिंग के स्वीट स्थान का पता लगाएं

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

मान लीजिए कि आप निम्नलिखित कार्ड कॉम्पोनेन्ट के लिए मार्कअप और CSS इम्प्लीमेंट करने जा रहे हैं:

card base design

डिजाइनों को देखते हुए आप निम्नलिखित स्टाइल पैटर्न की पहचान कर सकते हैं:

  • कार्ड बेस डिजाइन
  • कार्ड ग्रिड
  • कार्ड लिस्ट
  • कार्ड डार्क वर्जन

इसके बाद आप उन पैटर्नों के साथ CSS इम्प्लीमेंटेशन को ध्यान में रख सकते हैं और मार्गदर्शन के लिए डॉक्यूमेंटेशन का उपयोग कर सकते हैं। आरंभ करने के लिए, आपके "card.css" स्टाइलशीट में एक सरल परिचय शामिल हो सकता है:

आप परिचय में अधिक उपयोगी जानकारी शामिल कर सकते हैं, लेकिन जब बस कुछ साधारण शुरू कर रहे हैं, तो डॉक्यूमेंटेशन स्केलेटन को बनाए रखने में सहायता कर सकते हैं।

फिर, चलो उन सेक्शंस को जोड़ते हैं जहां आप अपनी स्टाइल में काम करेंगे:

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

जैसे ही आप कोड लिखते हैं, आप अपनी कमैंट्स के साथ अधिक विशिष्ट प्राप्त कर सकते हैं:

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

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

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

यहां Bootstrap फ्रेमवर्क के कुछ और उदाहरण हैं जो दिखाते हैं कि जब कमैंट्स उपयोगी होते हैं और जब इसे और अधिक विस्तार में जाने की आवश्यकता होती है।

उदाहरण #1

यह कमेंट स्पष्ट करती है कि ये स्टाइल्स क्यों मौजूद हैं और वे क्या कर रहे हैं। यह भी कम है और इस पॉइंट पर, एक कैसुअल लैंग्वेज में कम्युनिकेटिंग आईडिया।

उदाहरण #2

यह डॉक्यूमेंटेशन का एक बढ़िया उदाहरण है, जो गहराई में अधिक होता है, इम्प्लीमेंटेशन के फैसले के पीछे तर्क को समझाता है और अतिरिक्त जानकारी के लिंक प्रदान करता है।

इसे एक कदम आगे ले जाना

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

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

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

निष्कर्ष

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

उपयोगी संसाधन

रिमाइंडर: 8 सर्वोत्तम अभ्यास

  1. जमीन के नियम सेट करें
  2. डोक्युमेंटिंग की स्वीट जगह खोजें
  3. अपनी स्टाइलशीट के कंटेंट्स को इंडेक्स करें
  4. सेक्शंस में अपनी स्टाइलशीट्स को तोड़ना
  5. मन में एक स्टाइल गाइड के साथ CSS डॉक्यूमेंट
  6. लंबे स्टाइलशीट से बचें
  7. अपने कोडिंग मानकों को स्थापित करें
  8. अपने कोड बेस की संरचना समझाओ
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.