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

Google TypeScript स्टाइल का पालन करें गाइड देखें.

TypeScript और में माइग्रेशन ES6

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

यह करें

• लिंटिंग और फ़ॉर्मैटिंग टूल का इस्तेमाल करें.
  • हम eslint का इस्तेमाल करते हैं और हमारे पास .eslintrc.js फ़ाइल सेट अप करें हमारे पसंदीदा स्टाइल के नियमों के साथ.
  • हम ऑटोमैटिक फ़ॉर्मैटिंग के लिए, prettier का इस्तेमाल करते हैं.
  • लिंटर चलाने के लिए npm run lint और फ़ॉर्मैटर चलाने के लिए npm run format दबाएं.
• इंडेंट करने के लिए, टैब के बजाय स्पेस का इस्तेमाल करें.
• सेमीकोलन का इस्तेमाल करें.
• वैरिएबल और फ़ंक्शन के लिए camelCase का इस्तेमाल करें.
• क्लास के लिए TitleCase का इस्तेमाल करें.
• कॉन्सटेंट के लिए ALL_CAPS का इस्तेमाल करें.
• सभी कंट्रोल स्ट्रक्चर के लिए, ब्रैकेट का इस्तेमाल करें.
  • अपवाद: सिंगल-लाइन वाले if स्टेटमेंट के लिए ब्रैकेट हटाए जा सकते हैं.
• सिंगल कोट का इस्तेमाल करें (JSON लिखने के दौरान).
• for लूप में वैरिएबल फिर से दिखाएं. इसका मतलब है कि for (i = 0; ...) के बजाय हमेशा for (const i = 0; ...) लिखें.
  • ऐसा न करने से यह जोखिम बढ़ जाता है कि फ़ंक्शन करने के बाद, वैरिएबल ऑर्फ़न हो जाएगा और हैरान कर देने वाला ग्लोबल बन जाएगा.
• टिप्पणियों की शुरुआत कैपिटल लेटर से करें और आखिर में बिंदु लगाएं.
• TODOs में 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 कंपाइलर के हिसाब से एनोटेशन टाइप करें दस्तावेज़ में दिया गया है.

किसको दिखाई दे

ऐसे फ़ंक्शन या प्रॉपर्टी जिन्हें सिर्फ़ 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;
}