ब्लॉकली स्टाइल गाइड

Google टाइपस्क्रिप्ट स्टाइल गाइड पढ़ें.

टाइपस्क्रिप्ट और ES6 पर माइग्रेशन

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

ऐसा करें

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

यह न करें

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

टीएसडीओ

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

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

टाइप

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

किसको दिखे

जिन फ़ंक्शन या प्रॉपर्टी को सिर्फ़ ब्लॉकली लाइब्रेरी में ऐक्सेस किया जाना चाहिए उन्हें @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;
}