הערות ב-JavaScript: הערת שורה, הערת בלוק ומתי להשתמש בהן

שני סוגי הערות

ל-JavaScript יש שני תחבירים להערות. הערת שורה מתחילה ב-// ונמשכת עד סוף השורה:

// This is a single-line comment
let price = 100; // Comments can also trail code

console.log(price);

הערת בלוק מתחילה ב-/* ונגמרת ב-*/ הבא. היא יכולה להשתרע על כמה שורות שתרצו:

/*
  This is a block comment.
  It spans multiple lines.
  The interpreter ignores all of it.
*/

let total = 42;
console.log(total);

מנוע ה-JavaScript מתעלם לגמרי משתי הצורות. הן קיימות בשביל בני אדם: בשבילכם, בשביל חברי הצוות, ובשבילכם בעתיד, כשתקראו את הקוד הזה בעוד חצי שנה.

הערות שורה

// היא זו שתשתמשו בה הכי הרבה. כל מה שבאותה שורה אחרי // הוא הערה; השורה הבאה חוזרת להיות קוד:

// Calculate the tax-inclusive price
const price = 100;
const taxRate = 0.08;
const total = price * (1 + taxRate); // final amount the customer pays

console.log(total);

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

הערות בלוק

כדאי לבחור ב-/* */ בשני מקרים: הערה שצריכה יותר משורה אחת, והערה שיושבת באמצע ביטוי.

/*
 * Applies a bulk discount when the order qualifies.
 * Rules change per quarter - see pricing spec #214.
 */
function bulkDiscount(quantity, unitPrice) {
    return quantity >= 10 ? unitPrice * 0.9 : unitPrice;
}

// Inline in the middle of an expression:
const area = /* width */ 10 * /* height */ 5;

console.log(bulkDiscount(12, 50));
console.log(area);

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

/* outer /* inner */ still outer */
// SyntaxError - the first */ closed the block,
// and "still outer */" is now invalid code.

אם צריך להשבית בהערה קוד שכבר מכיל /* */, השתמשו ב-// בכל שורה במקום.

השבתת קוד בהערה

תוך כדי דיבוג תרצו לא פעם להשבית זמנית כמה שורות. שתי צורות ההערה עובדות:

function checkout(cart) {
    const subtotal = cart.reduce((sum, item) => sum + item.price, 0);

    // const shipping = calculateShipping(cart);
    // const total = subtotal + shipping;

    /*
    if (cart.length === 0) {
        throw new Error("Cart is empty");
    }
    */

    return subtotal;
}

console.log(checkout([{ price: 10 }, { price: 20 }]));

לכל עורך יש קיצור לזה, Ctrl+/ ב-Windows/Linux ו-Cmd+/ ב-Mac, שמפעיל ומכבה // בשורות שנבחרו. למדו אותו פעם אחת; תשתמשו בו כל יום.

קוד בהערה אמור להיות זמני. אל תעשו commit לבתי קברות של קוד מת עם // old version, keep just in case מעליהם. ניהול הגרסאות זוכר את הקוד הישן בשבילכם. מחקו אותו.

הסבירו את ה"למה", לא את ה"מה"

זה הכלל היחיד שמפריד בין הערות שימושיות לרעש. הקוד כבר מראה מה הוא עושה. הערה טובה מסבירה למה.

רעש:

// Set x to 10
let x = 10;

// Loop through the array
for (let i = 0; i < x; i++) {
    // Add i to the total
    console.log(i);
}

ההערות האלה לא אומרות לקורא שום דבר שהקוד לא אמר כבר. השוו:

// Stripe caps description at 500 chars - truncate before sending
function prepareDescription(text) {
    return text.slice(0, 500);
}

// Retry once: the auth service has a known cold-start timeout on first request
async function fetchUser(id) {
    try {
        return await api.get(`/users/${id}`);
    } catch {
        return await api.get(`/users/${id}`);
    }
}

שתי ההערות מתייחסות למשהו שקורא לא היה יכול להבין מהקוד לבדו: אילוץ חיצוני, התנהגות משונה מתועדת. זה הרף. אם הסרת ההערה לא הייתה מבלבלת אף אחד, ההערה לא הצדיקה את קיומה.

JSDoc: הערות שכלים קוראים

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

/**
 * Returns the final price after applying a percentage discount.
 *
 * @param {number} price - The original price in cents.
 * @param {number} percent - Discount percentage, 0 to 100.
 * @returns {number} The discounted price in cents.
 */
function discount(price, percent) {
    return price * (1 - percent / 100);
}

console.log(discount(10000, 20));

הפתיחה /** (שתי כוכביות) היא מה שמסמן את ההערה כ-JSDoc ולא כהערת בלוק רגילה. לא צריך JSDoc על כל פונקציה: הוא משתלם בעיקר ב-APIs ציבוריים, בפונקציות עזר משותפות ובכל מקום שבו הטיפוסים לא ברורים כבר מהקוד.

כמה הרגלים ששווה לשמור

• שמרו הערות קרוב לקוד שהן מתארות. הערה שנמצאת עשר שורות מעל השורה הרלוונטית נוטה לצאת מסנכרון כשהקוד משתנה.
• עדכנו הערות כשאתם משנים את הקוד. הערה מיושנת גרועה מאין הערה: היא ממש משקרת לקורא הבא.
• העדיפו שמות טובים יותר על פני יותר הערות. const d = 86400000; צריך הערה. const MILLISECONDS_PER_DAY = 86_400_000; לא.
• סמנו בעיות זמניות עם TODO: או FIXME:. רוב העורכים מדגישים אותן, וקל לחפש אותן אחר כך עם grep.

// TODO: לטפל נכון בהפרשי אזורי זמן אחרי שספריית התאריכים תשודרג
function daysBetween(a, b) {
    const MS_PER_DAY = 86_400_000;
    return Math.round((b - a) / MS_PER_DAY);
}

const start = new Date("2024-01-01");
const end = new Date("2024-01-15");
console.log(daysBetween(start, end));

הערה על הערות HTML מול הערות JavaScript

אם אתם כותבים JavaScript בתוך קובץ HTML, אל תבלבלו בין שני סגנונות ההערה. HTML משתמש ב-<!-- -->; JavaScript משתמשת ב-// וב-/* */. בתוך תגית <script> רק הצורות של JavaScript עובדות:

<script>
    // נכון: הערת JS בתוך <script>
    /* גם נכון */
    <!-- שגוי: זו הערת HTML והיא תשבור את ה-JS שלכם -->
    console.log("hi");
</script>

דפדפנים סבלו היסטורית <!-- --> בתוך סקריפטים מסיבות שקשורות לדפדפנים עתיקים, אבל התייחסו לזה כשבור והמשיכו הלאה.

הבא בתור: הצהרה על משתנים

עכשיו כשאתם יודעים להעיר על קוד, הגיע הזמן לכתוב קצת. ל-JavaScript יש שלוש דרכים להצהיר על משתנה, let, const ו-var, ובחירת הנכונה היא ההחלטה האמיתית הראשונה שתקבלו בכל שורה. זה הבא בתור.