دليل الأسلوب

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

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

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

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

• استخدِم أدوات فحص الأخطاء والتنسيق.
  • نستخدم eslint ولدينا eslint.config.mjs ملف تم إعداده بقواعد للنمط المفضّل لدينا.
  • نستخدم prettier للتنسيق التلقائي.
  • يمكنك تشغيل npm run lint لتشغيل أداة التدقيق و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 على الدوال أو السمات التي لا يمكن الوصول إليها إلا ضمن مكتبة Blockly. ويؤدي ذلك إلى منع ظهور هذه المواقع في المستندات العامة. يجب وضع مُعدِّلات مستوى العرض الأخرى في رمز 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;
}