راهنمای سبک بلوکی

راهنمای سبک Google TypeScript را دنبال کنید.

مهاجرت به TypeScript و ES6

Blockly در اصل در ES5.1 مطابق با نسخه قدیمی‌تر و کنونی راهنمای سبک Google JavaScript نوشته شده است. کد جدید نوشته شده باید با راهنمای سبک فعلی مطابقت داشته باشد و در صورت لزوم از ویژگی های زبان ES6 مانند let , const , class , destructuring assignment استفاده کند. کد موجود ممکن است به روز شود یا ممکن است از انطباق خارج شود. تیم Blockly سعی می کند بهترین تصمیم را با در نظر گرفتن سازگاری کد و تجربه کاربران کتابخانه اتخاذ کند - برای مثال، ممکن است ما تصمیم بگیریم که نام توابع عمومی را که دیگر با راهنمای سبک مطابقت ندارند، تغییر ندهیم.

انجام دادن

• از ابزارهای پرده و قالب بندی استفاده کنید.
  • ما از eslint استفاده می کنیم و یک فایل .eslintrc.js با قوانینی برای سبک دلخواه ما تنظیم شده است.
  • برای قالب بندی خودکار از زیباتر استفاده می کنیم.
  • npm run lint برای اجرای linter و npm run format برای اجرای قالب‌گیر اجرا کنید.
• تورفتگی با فاصله، نه برگه ها.
• از نقطه ویرگول استفاده کنید.
• از camelCase برای متغیرها و توابع استفاده کنید.
• از TitleCase برای کلاس ها استفاده کنید.
• از ALL_CAPS برای ثابت ها استفاده کنید.
• برای تمام سازه های کنترلی از مهاربند استفاده کنید .
  • استثنا: می‌توانید پرانتزهای if تک خطی را حذف کنید.
• از نقل قول های تکی استفاده کنید (به جز هنگام نوشتن JSON).
• متغیرها را دوباره در حلقه‌های for اعلام کنید. یعنی همیشه به جای for for (const i = 0; ...) for (i = 0; ...) بنویسید.
  • عدم انجام این کار این خطر را افزایش می دهد که پس از یک Refactor بالاتر در تابع، متغیر یتیم شده و به یک شگفتی جهانی تبدیل می شود.
• نظرات را با حروف بزرگ شروع کنید و با نقطه پایان دهید.
• مشکلات GitHub را با TODO ایجاد کنید و آنها را با استفاده از TODO(#issueNumber) پیوند دهید.
• همه چیز را با TSDoc حاشیه نویسی کنید.

نکن

• تورفتگی با زبانه ها.
• از خطوط زیر در انتهای نام متغیرها یا تابع ها استفاده کنید.
  • برخی از کدهای قبلی از زیرخط برای ویژگی ها یا توابع خصوصی یا داخلی استفاده می کنند. در حالی که این موارد ممکن است همچنان وجود داشته باشند، هیچ کد جدیدی نباید به دنبال این کنوانسیون اضافه شود.
• از snake_case استفاده کنید.
• از نقل قول های دوتایی استفاده کنید (به جز هنگام نوشتن JSON).
• از TSDoc ناقص استفاده کنید.
  • TSDoc ما به طور خودکار به عنوان بخشی از اسناد ما منتشر می شود.
• TODO (username) را بنویسید.
  • در عوض مشکلات GitHub را با TODO ایجاد کنید و آنها را با استفاده از TODO(#issueNumber) پیوند دهید.
• string.startsWith استفاده کنید. به جای آن از Blockly.utils.string.startsWith استفاده کنید.

TSDoc

تیم Blockly از TSDoc برای حاشیه نویسی کد ما و تولید اسناد استفاده می کند. ما TSDoc را برای تمام ویژگی های عمومی کلاس ها و برای همه توابع صادر شده انتظار داریم.

نظرات TSDoc باید با /** شروع و با */ ختم شوند تا به درستی تجزیه شوند.

انواع

نوع ها از TSDoc حذف می شوند زیرا این اطلاعات مستقیماً در کد TypeScript وجود دارد. اگر یکی از معدود فایل‌های جاوا اسکریپت باقی مانده را ویرایش می‌کنید، یادداشت‌های نوع را مطابق با اسناد Closure Compiler اضافه کنید.

دید

توابع یا ویژگی هایی که فقط باید در کتابخانه 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;
}