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

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

מעבר ל-TypeScript ול-ES6

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

מה מותר לעשות

• שימוש בכלים לזיהוי שגיאות בקוד ולעיצוב.
  • אנחנו משתמשים ב-eslint ויש לנו .eslintrc.js קובץ הגדרה עם כללים לסגנון המועדף עלינו.
  • לעיצוב האוטומטי אנחנו משתמשים בערך יפה יותר.
  • מריצים את הפקודה 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 ולקשר אותן באמצעות 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;
}