הערות ב-Java: הערת שורה, הערה מרובת שורות ו-Javadoc

בשביל מה יש הערות

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

ל-Java יש שלושה סוגי הערות: הערות שורה (//), הערות בלוק מרובות שורות (/* */) והערות תיעוד Javadoc (/** */). כולן עושות את אותה עבודה בסיסית, הקומפיילר מתעלם מהן, אבל כל אחת מתאימה למצבים אחרים.

הערות שורה

שני לוכסנים (//) פותחים הערה שנמשכת עד סוף השורה הנוכחית. הקומפיילר מדלג על כל מה שבין ה-// לסוף השורה.

public class Main {
    public static void main(String[] args) {
        // מדפיס ברכה לקונסולה
        System.out.println("Hello, Java!");

        int score = 90; // הערה יכולה לבוא גם אחרי קוד
        System.out.println(score);
    }
}

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

הערות בלוק מרובות שורות

כשההערה נפרשת על כמה שורות, הערת בלוק נקייה יותר מאשר להוסיף // בתחילת כל שורה. הערת בלוק מתחילה ב-/* ומסתיימת ב-*/. הקומפיילר מתעלם מכל מה שביניהם, לא משנה כמה שורות.

public class Main {
    public static void main(String[] args) {
        /*
         * התוכנית הזו מדגימה הערת בלוק.
         * הכוכביות בתחילת כל שורה הן רק
         * מוסכמה לשיפור הקריאות: הן לא חובה.
         */
        System.out.println("Block comments are handy.");
    }
}

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

הפיכת קוד להערה

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

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

הריצו את הקוד ותראו שרק שתי שורות ה-"runs" מודפסות. הקריאות ל-println שהפכו להערה בלתי נראות לקומפיילר.

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

הערות תיעוד Javadoc

הערת Javadoc נראית כמו הערת בלוק אבל מתחילה ב-/**, עם שתי כוכביות. היא נועדה לתעד מחלקה, מתודה או שדה, והיא נמצאת ישירות מעל מה שהיא מתארת. הכלי javadoc הופך אותן לתיעוד API ב-HTML שאפשר לדפדף בו, וסביבות פיתוח מציגות אותן כחלוניות מידע במעבר עכבר.

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

התגיות @param, @return ו-@throws הן שדות מובנים שהכלים מבינים. מבחינת הקומפיילר זו עדיין סתם הערה שמתעלמים ממנה: כל הערך הוא בתיעוד שהיא מייצרת וברמזים שסביבת הפיתוח נותנת למפתחים אחרים (ולכם, בעוד חצי שנה).

הערות טובות מול רעש

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

// רע: רק חוזר על מה שהקוד עושה באופן ברור
int i = i + 1; // מוסיף אחד ל-i

// טוב יותר: מסביר את הסיבה, שהקוד לא יכול להראות
retries++; // ממתין ומנסה שוב; ה-API מוגבל ל-5 בקשות בשנייה

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

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

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