הערות בג'אווה: לא הכל כל כך פשוט

מבוא

הערות - נראה שזה יכול להיות פשוט יותר, ולמה לכתוב מאמר שלם. אבל זה לא כל כך פשוט. כמו שהבוס שלי אמר, כל אחד יכול לכתוב קוד, אבל לכתוב תגובה טובה זה קשה. רוב קורסי השפה מתחילים ב-Hello World המסורתי. אפילו ב- Oracle Tutorials, בסעיף "תחילת העבודה", אנחנו מתחילים עם "Hello World!" יישום . וכבר משורות הקוד הראשונות אנו רואים אותן - הערות Java. חשיבותם מודגשת גם על ידי העובדה שבמסמך כה חשוב כמו אמנת Java Code, ניתן להערות סעיף נפרד: הערות . על פי התיעוד, הערות ב-Java מחולקות לשני סוגים:

• הערת יישום (או הערת קוד);
• הערה מתעדת.

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

הערות קוד Java

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

• אותיות קטנות (כלומר מתואר בשורה אחת)

  // Строчный комментарий
  System.out.println("Hello, World!");




• בלוק (כלומר הם מתוארים כגוש שלם, כי הם לא מתאימים על קו אחד)

  /*
   * Блочный комментарий
   */
  System.out.println("Hello");

תכונה מעניינת של הערת בלוק היא שאם נתחיל אותה עם " /*- " (כלומר להוסיף סימן מינוס אחרי הכוכבית), אז הטקסט של הערת בלוק זה לא יעוצב. מעניין, אבל בעזרת הערות מסוימות אתה יכול לתת כמה רמזים ל-IDE. לדוגמה, באמצעות ההערות המוטבעות " //@formatter:on " ו- " //@formatter:off " ב-Eclipse IDE אתה יכול להשבית את העיצוב עבור קטעי קוד. עליך להשתמש בהערות במשורה ורק במידת הצורך. לדוגמה, אתה יכול לקרוא מאמר בנושא זה: "אל תכתוב הערות על קוד!" . יש ספר נהדר בשם קוד נקי: יצירה, ניתוח וחידוש מאת רוברט מרטין. יש לו פרק נפרד "הערות". כאפיגרף לפרק זה, ציטוט מצוין לא פחות: "אל תגיב על קוד גרוע - כתוב אותו מחדש" מאת בריאן וו. קרניגאן ופ.ג'יי פלוור. ניתן למצוא את הפרק הזה ב- Google Books . המשמעות הכללית יכולה לבוא לידי ביטוי בציטוט אחד ממנו:

בכל פעם שאתה מגיב, תתכווץ ותרגיש כמו כישלון".

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

// TODO: Добавить World
System.out.println("Hello, ");

הנקודה בהם היא שניתן לטפל בהם בצורה מיוחדת ב-IDE. לדוגמה, ב-IDEA הם נאספים בלשונית נפרדת, שבה אתה יכול לראות אותם: וחידה קטנה עם הערה: השורה "http://google.com" היא שורה תקפה בתוך השיטה, כי http כאן הוא למעשה תג, ולאחר מכן תגובה. לעתים קרובות הערות רבות יכולות לעבור מהערות קוד להערות תיעוד, עליהן נדבר בהמשך.

הערות לתיעוד

הערות תיעוד מתארות את ה-API הציבורי. API הוא ממשק תכנות היישומים, כלומר אותם מחלקות ושיטות הזמינות למפתחים אחרים לביצוע כל פעולה. בקיצור, ההערות הללו צריכות להסביר מדוע נוצרה מחלקה וחבילה זו או אחרת ומה עושה שיטה זו או אחרת. ניתן גם לתאר שדות כיתה במידת הצורך. זה בדיוק מה שאנחנו רואים בטיפים של ה-IDEs שלנו, המוצגים כ-JavaDoc. לדוגמה: אם ניכנס לשיטה זו, נוכל לראות מאיפה מגיע הטקסט הזה: שוב, ראה את אמנת קוד Java: אמנת קוד על אופן העיצוב הנכון של JavaDoc . הם דומים במקצת להערות חסימה, אבל במקום כוכבית אחת (לא אסטריקס)) משתמשים בשניים. דוגמה ל-JavaDoc ניתנה למעלה. אין טעם לתאר את כל האפשרויות, שכן על כך כבר כתוב בתיעוד הרשמי של אורקל. לכן, אנו מסתכלים על כל מה שאתה צריך בתיעוד הרשמי של JavaDoc , סעיף "תיאורי תגים". לאורקל יש אפילו מדריך נפרד בנושא זה: כיצד לכתוב הערות מסמך עבור הכלי Javadoc . עצות כלים ב-IDE נחמדות, אבל הן למעשה מסמכים מסיבה כלשהי. בהתבסס על הערות JavaDoc אלה, נוצר תיעוד. יש כלי עזר מיוחד ל-javadoc עבור זה . כפי שאנו יכולים לראות, המדריך הזה מדבר על זה. תיאור של אופן השימוש בו נמצא באתר הרשמי של Oracle עבור JavaDoc . כדי לראות בעצמך איך זה נראה, אתה יכול ליצור ספריית משנה בספרייה עם שם החבילה, למשל: test . צור כיתה פשוטה עם הערות בתוכה. לדוגמה:

package test;

/**
 * This is a JavaDoc class comment
 */
public class JavaDocTest {

  /**
   * This is a JavaDoc public field comment
   */
  public static final String HELLO_MESSAGE = "Hello, World!";

  public static void main(String... args) {
    JavaDocTest.greetings();
  }

  /**
   * This is a JavaDoc public method comment
   */
  public static void greetings() {
    System.out.println(HELLO_MESSAGE);
  }
}

לאחר מכן, נוכל להריץ את הפקודה הבאה מהספרייה המכילה את ספריית החבילות שלנו: javadoc -d ./test test לאחר מכן, נראה את תהליך יצירת התיעוד. ואז נוכל לפתוח את index.html כדי לראות את המסמך שנוצר. לעתים קרובות תראה תיעוד API מתפרסם. לדוגמה, Spring Framework API .

סיכום

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