אתמול כתבתי על הפרידה של DHH מטייפסקריפט וראינו איך "יותר מדי טייפסקריפט" יכול להזיק. מעניין לשים לב שטייפסקריפט היא בעצם שפה גמישה להפליא, ואפשר להשתמש בה כמעט בלי להרגיש - כשהרעיון שבמקום להשתמש בטייפסקריפט כשפה נשתמש רק ביכולת לבדוק טיפוסים. בואו נלך לשחק עם זה בעזרת סטנדרט לכתיבת הערות בשם JSDoc.

1. מה זה JSDoc

לפני 24 שנים החברים בנטסקייפ חשבו שצריך להוסיף תיעוד מסודר יותר ל JavaScript והחליטו על המונח JSDoc, נגזרת או משחק על JavaDoc, כדי לתאר סטנדרט של כתיבת הערות על קוד שיכללו בין השאר מידע על טיפוסים שפונקציות מצפות לקבל ולהחזיר.

שיטת העבודה של JSDoc היא להוסיף תוויות מיוחדות להערות וכל תווית אומרת משהו על הפונקציה או על הקובץ, לדוגמה תווית @author אומרת מי כתב את הקובץ, תווית @param מתעדת פרמטר לפונקציה ותווית @returns מתעדת את ערך ההחזר של הפונקציה.

2. איך JSDoc קשור לטייפסקריפט?

כשטייפסקריפט נכתבה JSDoc כבר היתה סטנדרט קיים ובשביל שיהיה לכולם קל לשלב את טייפסקריפט מייקרוסופט כללה תמיכה ב JSDoc בתוך הקומפיילר של טייפסקריפט. זה אומר שטייפסקריפט יכולה לקרוא קובץ JavaScript המכיל מידע על טיפוסים בפורמט JSDoc ולהשתמש במידע זה.

מאחר וטייפסקריפט משולבת ב VSCode אני יכול מתוך סביבת הפיתוח אפילו בקבצי JavaScript לקבל הערות על טיפוסים בלי להוסיף שום מידע חדש או ספציפי לטייפסקריפט. אפשר למצוא את הפרטים על TypeScript ו JSDoc בתיעוד כאן: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html

3. הדגמה: פונקציה שמקבלת מספר

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

function twice(x) {
  return x * 2;
}

דרך קלה לספר למחשב (ולאנשים) שהפונקציה צריכה לקבל מספר ולהחזיר מספר היא JSDoc. אני מוסיף את ההערה:

/**
 * Doubles the given number
 * @param {number} x an input number
 * @returns {number} x * 2
 */
function twice(x) {
  return x * 2;
}

נוסיף לפרויקט גם קובץ בשם tsconfig.json. למרות השם, אני לא מתקין TypeScript ולא מוסיף דרישה לקומפילציה. כל הקוד שאני כותב יכול להיטען כמו שהוא בדפדפן. תוכן הקובץ יהיה:

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true
  }
}

אבל זה כל מה ש VS Code היה צריך בשביל לבדוק את תקינות הטיפוסים של הקוד בעזרת הערות ה JSDoc שרשמתי. עכשיו הקוד הבא מציג פס אדום ב VS Code מתחת לטקסט a בהפעלת הפונקציה:

/**
 * Doubles the given number
 * @param {number} x an input number
 * @returns {number} x * 2
 */
function twice(x) {
  return x * 2;
}

// show a red line under the 'a'
console.log(twice('a'));

4. הדגמה: פונקציה שמקבלת אלמנט HTML

בואו ננסה אחד יותר מסובך וגם פה אין שום בעיה. שימו לב לקוד הבא:

/**
 * 
 * @param {HTMLElement} element 
 * @param {{text?: string, backgroundColor?: string}} textAndStyle 
 */
function addTextAndStyle(element, textAndStyle) {
  if (textAndStyle.text) {
    element.textContent = textAndStyle.text;
  }
  if (textAndStyle.backgroundColor) {
    element.style.backgroundColor = textAndStyle.backgroundColor;
  }
}

addTextAndStyle(document.querySelector('#app'), { text: 'hello world'});

הפונקציה מקבלת שני פרמטרים, הראשון הוא אוביקט מסוג HTMLElement והשני הוא אוביקט שאולי מכיל מפתח בשם text ואולי מכיל מפתח בשם backgroundColor.

5. טיפ לאנשים שרוצים לשלב טייפסקריפט לאט

הבחירה בכתיבת טיפוסים ב JSDoc ובדיקתם בתוך עורך הטקסט היא בחירה הרבה יותר קלה מכניסה בכל הכח לעולם של טייפסקריפט. אתם לא צריכים ללמוד תחביר חדש ואם אתם לא בטוחים מה לכתוב בפרמטר תמיד אפשר להשתמש בכוכבית. אפילו במקרה הגרוע שעשיתם טעות בטיפוסים, הקוד עדיין ירוץ בדפדפן בלי בעיה.

כתיב כזה יכול לעזור להרגיל את חברי הצוות לאט להשתמש בכתיב הטיפוסים, כדי שכשיגיע הרגע לכתוב טייפסקריפט תהיה לכם את התשתית במקום והמוכנות ללמוד כלים חדשים שיעזרו להתמודד עם כפילויות בהגדרת הטיפוסים.