מדריך סגנון

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

מעבר ל-TypeScript ול-ES6

Blockly נכתב במקור ב-ES5.1 בהתאם לגרסה ישנה יותר של מדריך הסגנון של Google ל-JavaScript. קוד שנכתב מחדש צריך לעמוד בדרישות של מדריך הסגנון הנוכחי ולהשתמש בתכונות של שפת ES6 כמו let, ‏ const, ‏ class, הקצאה של מבנה מפורק (destructuring assignment) במקרים הרלוונטיים. יכול להיות שהקוד הקיים יתעדכן או שיישאר לא תואם. צוות 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 ולקשר אותן באמצעות 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. אם אתם עורכים אחד מקובצי ה-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;
}