מדריך סגנון של Blockly

פעלו לפי מדריך הסגנון של Google TypeScript.

העברה אל TypeScript ו-ES6

חסימת הכיתוב חסימה נכתבה במקור ב-ES5.1 בהתאם לגרסה ישנה יותר של מדריך הסגנון של Google JavaScript. הקוד החדש שנכתב צריך לעמוד בדרישות של מדריך הסגנון הנוכחי, ולהשתמש בתכונות של שפת ES6 כמו let, const ו-class, כדי לשנות את ההקצאה, במקרים הרלוונטיים. ייתכן שהקוד הקיים יעודכן או לא יעמוד בדרישות. צוותBlockly מנסה לקבל את ההחלטה הטובה ביותר תוך התחשבות בעקביות של הקוד ובחוויה של המשתמשים בספרייה. לדוגמה, יכול להיות שנחליט לא לשנות את השם של פונקציות ציבוריות שכבר לא עומדות בדרישות של מדריך הסגנון.

מה מותר לעשות

• להשתמש בכלי linting ובכלי עיצוב.
  • אנחנו משתמשים ב-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

צוות החסימה משתמש ב-TSDoc כדי להוסיף הערות לקוד שלנו וליצור מסמכים. אנחנו מצפים בעזרת TSDoc לכל הנכסים הציבוריים של כיתות ולכל הפונקציות שיוצאו.

כדי שתגובות TSDoc ינותחו כמו שצריך, הן חייבות להתחיל ב-/** ולהסתיים ב-*/.

סוגים

הסוגים לא נכללים ב-TSDoc כי המידע הזה נמצא ישירות בקוד TypeScript. אם אתם עורכים את אחד מקובצי ה-JavaScript שנותרו, חשוב לכלול במאמרי העזרה של 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;
}