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

اتّبِع دليل أسلوب Google TypeScript.

النقل إلى TypeScript وES6

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

الإجراءات التي يُنصح بها

• استخدام أدوات التركيب والتنسيق
  • نستخدم eslint ولدينا ملف .eslintrc.js تم إعداده بقواعد خاصة بالأسلوب المفضّل لدينا.
  • نستخدم أجمل للتنسيق التلقائي.
  • شغِّل npm run lint لتشغيل linter وnpm run format لتشغيل التنسيق.
• إضافة مسافة بادئة بمسافات، وليس بعلامات جدولة
• استخدِم semicolons.
• استخدِم 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

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

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

الأنواع

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

مستوى العرض

يجب إضافة تعليقات توضيحية للدوال أو الخصائص التي يجب الوصول إليها داخل مكتبة حظر باستخدام @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;
}