הערות Java

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

הערות Java: מדוע הן חשובות

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

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

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

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

סוגי הערות ב-Java

למרות העובדה שאתה יכול לכתוב הכל והכל בתגובות, ישנם סוגים מסוימים של הערות ב-Java וכללים לשימוש בהם. בהערות Java קר להיות:

• הערות בשורה אחת
• הערות מרובות שורות
• הערות תיעוד

הערות בשורה אחת

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

//here is a single line comment.

ניקח דוגמה לסוג זה של הערות Java:

public class CommentsDemo1 {
   public static void main(String[] args) {
       System.out.println("This text is visible for Java compiler");
       //this text is single line comment 
//This one is also single line comment
//they both (and me) are invisible for compiler
   }
}

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

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

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

/*This comment 
is
Multi line comment 
we can describe here 
what we need */

בואו נביא דוגמה להערות מרובות שורות בקוד

public class RleTest {

   /*
   Run Length Encoding (RLE),  a data compression algorithm
   that replaces repeated characters (series)
   with one character and the number of its repetitions.
  
   this method is to decode a String using run-length encoding

    */
   private static String decodeRle(String encoded) {
       if (encoded.isBlank()) return "";
       StringBuilder result = new StringBuilder();
       int count = 0;
       char baseChar = encoded.charAt(0);
       for (int i = 1; i <= encoded.length(); i++) {
           char c = i == encoded.length() ? '$' : encoded.charAt(i);
           if (Character.isDigit(c)) {
               count = count * 10 + Character.digit(c, 10);
           } else {
               do {
                   result.append(baseChar);
                   count--;
               } while (count > 0);
               count = 0;
               baseChar = c;
           }
       }
       return result.toString();
   }
   public static void main(String[] args) {
       System.out.println(decodeRle("C3ecddf8"));
   }
}

הערות תיעוד Java

זהו סוג מיוחד של הערות Java המשמשות ליצירת דף תיעוד. בדרך כלל מפתחים כותבים הערות תיעוד באמצעות Javadoc, מחולל תיעוד להפקת תיעוד API בפורמט HTML מקוד מקור Java. הפורמט של מסמכים בשימוש על ידי Javadoc הוא התקן התעשייה לתיעוד שיעורי Java וה-IDEs הפופולריים ביותר כגון IntelliJ IDEA ו-Eclipse, מייצרים אוטומטית Javadoc HTML. להערות התיעוד של Java יש את התחביר שלהלן:

/**
Some important Javadoc comments here 
You don’t know it yet, but Javadoc rulez 

@author  Java Developer
*/

הנה דוגמה: זה קטע של מחלקה Java Short . אגב, אתה יכול להסתכל על כל קוד מחלקה של Java מה-IDE שלך (למשל ב-IntelliJ IDEA מ-Windows פשוט הקש ctrl+LBM או ctrl+b (ב-Windows) על כל שם של מחלקה או שיטה).

package java.lang;

import jdk.internal.HotSpotIntrinsicCandidate;
import jdk.internal.misc.VM;

/**
* The {@code Short} class wraps a value of primitive type {@code
* short} in an object.  An object of type {@code Short} contains a
* single field whose type is {@code short}.
*
* <p>In addition, this class provides several methods for converting
* a {@code short} to a {@code String} and a {@code String} to a
* {@code short}, as well as other constants and methods useful when
* dealing with a {@code short}.
*
* @author  Nakul Saraiya
* @author  Joseph D. Darcy
* @see     java.lang.Number
* @since   1.1
*/
public final class Short extends Number implements Comparable<Short> {

   /**
    * A constant holding the minimum value a {@code short} can
    * have, -2<sup>15</sup>.
    */
   public static final short   MIN_VALUE = -32768;

   /**
    * A constant holding the maximum value a {@code short} can
    * have, 2<sup>15</sup>-1.
    */
   public static final short   MAX_VALUE = 32767;

   /**
    * The {@code Class} instance representing the primitive type
    * {@code short}.
    */
   @SuppressWarnings("unchecked")

הנה קוד Java של השיטה המוכרת והאהובה על כל המתחילים println() עם הערה כזו:

/**
* Prints a String and then terminate the line.  This method behaves as
* though it invokes {@link #print(String)} and then
* {@link #println()}.
*
* @param x  The {@code String} to be printed.
*/
public void println(String x) {
   if (getClass() == PrintStream.class) {
       writeln(String.valueOf(x));
   } else {
       synchronized (this) {
           print(x);
           newLine();
       }
   }
}

ל-Javadoc יש כמה תגיות Javadoc מיוחדות המסומנות ב-@ שתוכלו לראות בקוד למעלה. הדוגמה של תג Javadoc כזה היא @author שמוסיף שם של מחבר המחלקה. תג נוסף של Javadoc הוא @מאחר שהוא מוסיף הערה המציינת שהמחלקה הזו נמצאת בשימוש מאז הגרסה שצוינה של Java. כתיבת מסמכי Javadoc טובים דורשת ידע וניסיון (וסבלנות!). תוכל למצוא מידע נוסף על Javadoc בתיעוד הרשמי כיצד לכתוב הערות מסמך עבור הכלי Javadoc .

נ.ב כמה הערות מצחיקות דוגמאות מהחיים האמיתיים

/**
*Dear Maintainer
*
*Once you are done trying to 'optimize' this routine,
*and you have realized what a terrible mistake that was,
*please increment the following counter as a warning
*to the next guy.
*
*total_hours_wasted_here = 73
*/

Exception up = new Exception("Something is really wrong.");
throw up;  //ha ha

// When I wrote this, only God and I understood what I was doing
// Now, God only knows

// sometimes I believe compiler ignores all my comments

/**
Always returns true.
*/
public boolean isAvailable() {
return false;
}

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