स्टाइल गाइड

Google TypeScript स्टाइल के लिए बनी गाइड का पालन करें.

TypeScript और ES6 पर माइग्रेट करना

Blockly को मूल रूप से ES5.1 में लिखा गया था. यह Google JavaScript स्टाइल गाइड के पुराने और तब के मौजूदा वर्शन के मुताबिक था. नया कोड, मौजूदा स्टाइल गाइड के मुताबिक होना चाहिए. साथ ही, let, const, class जैसी ES6 भाषा की सुविधाओं का इस्तेमाल करना चाहिए. इसके अलावा, जहां भी लागू हो, डीस्ट्रक्चर करने वाले असाइनमेंट का इस्तेमाल करना चाहिए. मौजूदा कोड को अपडेट किया जा सकता है या उसे अनुपालन से बाहर रखा जा सकता है. Blockly टीम, कोड की एकरूपता और लाइब्रेरी के उपयोगकर्ताओं के अनुभव को ध्यान में रखकर सबसे सही फ़ैसला लेने की कोशिश करती है. उदाहरण के लिए, हम उन सार्वजनिक फ़ंक्शन का नाम बदलने का विकल्प नहीं चुन सकते जो अब स्टाइल गाइड का पालन नहीं करते.

यह करें

• लिंटिंग और फ़ॉर्मैटिंग टूल का इस्तेमाल करें.
  • हम eslint का इस्तेमाल करते हैं. साथ ही, अपनी पसंदीदा स्टाइल के लिए नियमों के साथ eslint.config.mjs फ़ाइल सेट अप की है.
  • हम ऑटोमैटिक फ़ॉर्मैटिंग के लिए, prettier का इस्तेमाल करते हैं.
  • लिंटर चलाने के लिए npm run lint और फ़ॉर्मैटर चलाने के लिए npm run format दबाएं.
• टेक्स्ट को इंडेंट करने के लिए, स्पेस का इस्तेमाल करें, न कि टैब का.
• सेमीकोलन का इस्तेमाल करें.
• वैरिएबल और फ़ंक्शन के लिए camelCase का इस्तेमाल करें.
• क्लास के लिए TitleCase का इस्तेमाल करें.
• कॉन्स्टेंट के लिए ALL_CAPS का इस्तेमाल करें.
• सभी कंट्रोल स्ट्रक्चर के लिए, ब्रैकेट का इस्तेमाल करें.
  • अपवाद: एक लाइन वाले if स्टेटमेंट के लिए, ब्रैकेट छोड़े जा सकते हैं.
• सिंगल कोट का इस्तेमाल करें (JSON लिखते समय को छोड़कर).
• for लूप में वैरिएबल फिर से तय करें. इसका मतलब है कि for (i = 0; ...) के बजाय हमेशा for (const i = 0; ...) लिखें.
  • ऐसा न करने पर, फ़ंक्शन में ऊपर की ओर रीफ़ैक्टर करने के बाद, वैरिएबल को ऑरफ़न कर दिया जाएगा और वह अचानक ग्लोबल हो जाएगा.
• टिप्पणियों की शुरुआत कैपिटल लेटर से करें और आखिर में बिंदु लगाएं.
• 'बचे हुए काम' के साथ GitHub समस्याएं बनाएं और उन्हें TODO(#issueNumber) का इस्तेमाल करके लिंक करें.
• TSDoc की मदद से, सभी चीज़ों पर एनोटेशन जोड़ें.

यह न करें

• टैब की मदद से इंडेंट करें.
• वैरिएबल या फ़ंक्शन के नामों के आखिर में अंडरलाइन का इस्तेमाल करें.
  • कुछ पुराने कोड में, निजी या इंटरनल प्रॉपर्टी या फ़ंक्शन के लिए अंडरस्कोर का इस्तेमाल किया जाता है. ये कोड मौजूद रहेंगे, लेकिन इस कॉन्वेंशन के हिसाब से कोई नया कोड नहीं जोड़ा जाना चाहिए.
• snake_case का उपयोग करें.
• डबल कोट का इस्तेमाल करें (JSON लिखते समय छोड़ें).
• गलत तरीके से बनाए गए TSDoc का इस्तेमाल करना.
  • हमारा TSDoc, दस्तावेज़ के हिस्से के तौर पर अपने-आप पब्लिश हो जाता है.
• TODO (username) लिखें.
  • इसके बजाय, TODOs के साथ GitHub समस्याएं बनाएं और उन्हें TODO(#issueNumber) का इस्तेमाल करके लिंक करें.
• string.startsWith का उपयोग करें. इसके बजाय, Blockly.utils.string.startsWith का इस्तेमाल करें.

TSDoc

Blockly की टीम, अपने कोड पर एनोटेशन लगाने और दस्तावेज़ जनरेट करने के लिए, TSDoc का इस्तेमाल करती है. हमें उम्मीद है कि क्लास की सभी सार्वजनिक प्रॉपर्टी और एक्सपोर्ट किए गए सभी फ़ंक्शन के लिए, TSDoc का इस्तेमाल किया गया हो.

TSDoc टिप्पणियों को सही तरीके से पार्स करने के लिए, उन्हें /** से शुरू और */ पर खत्म करना चाहिए.

टाइप

टाइप को TSDoc से हटा दिया जाता है, क्योंकि यह जानकारी सीधे TypeScript कोड में मौजूद होती है. अगर आपको बचे हुए कुछ JavaScript फ़ाइलों में से किसी एक में बदलाव करना है, तो Closure Compiler के दस्तावेज़ के मुताबिक, एनोटेशन शामिल करें.

किसको दिखे

जिन फ़ंक्शन या प्रॉपर्टी को सिर्फ़ Blockly लाइब्रेरी में ऐक्सेस किया जाना चाहिए उन पर @internal का एनोटेशन लगाना चाहिए. इससे, इन प्रॉपर्टी को सार्वजनिक दस्तावेज़ में दिखने से रोका जा सकता है. अन्य प्रॉपर्टी के दिखने के तरीके में बदलाव करने वाले एलिमेंट को सीधे तौर पर TypeScript कोड में डाला जाना चाहिए, न कि TSDoc में.

प्रॉपर्टी

प्रॉपर्टी के लिए TSDoc में, प्रॉपर्टी की जानकारी शामिल होनी चाहिए. जिन प्रॉपर्टी के बारे में जानकारी अपने-आप मिल जाती है उनके लिए ब्यौरा नहीं दिया जा सकता.

/**
  *   The location of the top left of this block (in workspace coordinates)
  *   relative to either its parent block, or the workspace origin if it has no
  *   parent.
  *
  *   @internal
  */
relativeCoords = new Coordinate(0, 0);

फ़ंक्शन

फ़ंक्शन के लिए एनोटेशन में ये शामिल होने चाहिए

• फ़ंक्शन के बारे में जानकारी
• हर पैरामीटर के लिए एक @param टैग, इसमें ये भी शामिल हैं
  • नाम
  • ब्यौरा
• अगर फ़ंक्शन से कोई वैल्यू मिलेगी, तो @returns टैग के साथ वैल्यू की जानकारी दी जाएगी.

अगर फ़ंक्शन, पैरामीटर या रिटर्न वैल्यू के बारे में जानकारी अपने-आप मिल जाती है, तो उनके लिए ब्यौरा नहीं दिया जा सकता.

उदाहरण के लिए:

/**
 *   Find the workspace with the specified ID.
 *
 *   @param id ID of workspace to find.
 *   @returns The sought after workspace or null if not found.
 */
export function getWorkspaceById(id: string): Workspace | null {
  return WorkspaceDB_[id] || null;
}