دليل نمط بشكل متقطّع

اتباع نمط Google TypeScript الدليل.

نقل البيانات إلى TypeScript وES6

تم كتابة Blockly في الأصل باستخدام ES5.1 بما يتوافق مع إصدار قديم كان ساريًا في ذلك الوقت من دليل أسلوب JavaScript في Google . مكتوب حديثًا يجب أن يتوافق الرمز مع دليل التنسيق الحالي وأن يستخدم ميزات اللغة ES6 مثل let وconst وclass، ما يؤدي إلى إتلاف المهمة حيثما ينطبق ذلك. قد يتم تعديل الرمز الحالي أو قد لا يلتزم بالسياسات. يحاول فريق Blockly اتخاذ أفضل قرار مع الأخذ في الاعتبار اتساق الرموز البرمجية وتجربة مستخدمي المكتبة. على سبيل المثال، قد نختار عدم إعادة تسمية الدوال العامة التي لم تعُد متوافقة مع دليل الأنماط.

الإجراءات الموصى بها

• استخدِم أدوات فحص الأخطاء والتنسيق.
  • نستخدم eslint ولدينا .eslintrc.jsملف تم إعداده بقواعد للنمط المفضّل لدينا.
  • نستخدم prettier للتنسيق التلقائي.
  • شغِّل npm run lint لتشغيل linter وnpm run format لتنفيذ العملية. وتنسيقه.
• مسافة بادئة مع مسافات، وليس علامات جدولة.
• استخدِم الدلالات.
• استخدِم camelCase للمتغيّرات والدوال.
• استخدِم "TitleCase" للصفوف.
• استخدِم ALL_CAPS للثوابت.
• استخدام الأقواس لجميع بُنى التحكّم.
  • استثناء: يمكنك حذف الأقواس في عبارات if المكوّنة من سطر واحد.
• استخدِم علامات الاقتباس المفردة (باستثناء عند كتابة JSON).
• إعادة تعريف المتغيّرات في حلقات for بعبارة أخرى، يجب دائمًا كتابة for (const i = 0; ...) بدلاً من for (i = 0; ...).
  • يؤدي عدم إجراء ذلك إلى زيادة خطر أن يصبح المتغيّر متعلّقًا بغير عنصر بعد إجراء إعادة تنظيم في رمز برمجي أعلى في دالة، ما يؤدي إلى أن يصبح متغيّرًا عامًا بشكل غير متوقّع.
• ابدأ التعليقات بأحرف كبيرة وانتهِ بها بنقاط.
• إنشاء مشاكل GitHub باستخدام "المهام" وربطها باستخدام TODO(#issueNumber).
• أضِف تعليقات توضيحية على كل المحتوى باستخدام TSDoc.

الإجراءات غير المُوصى بها

• اضبط المسافة البادئة باستخدام علامات التبويب.
• استخدِم الشرطة السفلية في نهاية أسماء المتغيّرات أو الدوالّ.
  • تستخدم بعض التعليمات البرمجية السابقة الشرطات السفلية للخصائص الخاصة أو الداخلية أو الأخرى. مع أنّه قد يستمر استخدام هذه الرموز، يجب عدم إضافة أي رمز جديد وفقًا لهذه الاتفاقية.
• استخدام حساب "snake_case".
• استخدِم علامتَي اقتباس مزدوجتَين (باستثناء كتابة ملف JSON).
• استخدام ملف TSDoc بتنسيق غير صحيح
  • يتم نشر TSDoc تلقائيًا كجزء من مستنداتنا.
• كتابة TODO (username)
  • بدلاً من ذلك، يمكنك إنشاء مشاكل على GitHub تتضمّن المهام التي يجب إكمالها وربطها باستخدام TODO(#issueNumber).
• استخدام حساب "string.startsWith". يمكنك استخدام Blockly.utils.string.startsWith كبديل.

TSDoc

يستخدم فريق Blockly TSDoc لإضافة تعليقات توضيحية إلى الرموز البرمجية إنشاء الوثائق. نتوقع استخدام TSDoc لجميع الخصائص العامة للفئات، وجميع الدوال التي تم تصديرها.

يجب أن تبدأ تعليقات TSDoc بـ /** وتنتهي بـ */ ليتم تحليلها بشكل صحيح.

الأنواع

يتم حذف الأنواع من TSDoc لأنّ هذه المعلومات متوفّرة في رمز TypeScript بشكل مباشر. إذا كنت تعدّل أحد ملفات JavaScript القليلة المتبقية، أدرِج annotated type وفقًا لمستندات Closure Compiler .

مستوى الرؤية

الدوال أو الخصائص التي يجب الوصول إليها فقط داخل مكتبة حظر يجب إضافة تعليقات توضيحية إليه باستخدام @internal. يمنع هذا هذه الخصائص من يظهر في الوثائق العامة. يجب وضع مُعدِّلات visibility الأخرى في رمز 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;
}