מסמכים עם הערות
הוצג| English | משמעות |
|---|---|
| comment/ˈkɒment/ | תcomment |
הערה לא תתיק נוס פעילה
- עבור מחיר 100,
total = price * 10 / 100;מחשב 10 גם אם הערה אומרת “סכום בתשלום לאחר עשר אחוזי הנחה”. עריכת הסבר זו אינה הופכת את הביטוי לחשב 90. - שנה את הביטוי הפעיל ל-
price * 90 / 100כדי לחשב את הסכום המיועד לדמייה בדוגמה זו של מספרים שלמים. הערות יכולות להבהיר מדיניות מתוכננת; ודא שהקוד מממש אותה.
זיהוי טקסט הנשלל מקוד
//פותח הערה החלה בקו השורה./*פותח הערת בלוק החלה בקו השורה הבא*/; הערות בלוק לא משתלבות אחת בתוך השנייה. תחומי הפרדה בתוך ליטרלי מחרוזת הם טקסט, ולכן"https://example.com"לא פותח הערה.- טקסט ההערות אינו מתבצע כפקודות ג'אבה. הוספת הסבר נפרדת משארת את הביטוי הפעיל ללא שינוי; הצבת
//לפני הקצאה פעילה מסירה את ההקצה מהקוד המוצג ומסוגלת לשנות התנהגות.
שמור תגי Javadoc בשורות נפרדות
- הערעת מסמך
/** ... */המופיעה מיד לפני הכרזה יכולה לעובד על ידי Javadoc. הסיכום שלה מסביר את הפעולה; תגי בלוק כמו@paramו-@returnמתחילים בשורות משלהם לאחר רווחים רגילים ואי-רווחים אפשריים ו-*. - המחלקה המלאה למטה מסמכת קרן רדיוס שאינו שלילית והיא מחזירה שטח מעגלה. התגים מתארים קלט, פלט וקלט שנדחה; הערה לבדה אינה מאפסת תנאי פתיחה, ולכן השיטה בודקת במפורש רדיוסים שליליים.
/** Circle-area calculations for finite radii. */
public class AreaDoc {
/**
* Returns the area of a circle for a finite radius.
* @param r the non-negative radius
* @return the area in squared radius units
* @throws IllegalArgumentException if r is negative
*/
public static double area(double r) {
if (r < 0) {
throw new IllegalArgumentException("Negative radius");
}
return Math.PI * r * r;
}
}
Javadoc מזהה @param כתג בלוק כאשר הוא מובא לאחר טקסט סיכום באותה שורה.
Difficulty 1/5 · 100 coins + a small bonus on first completion today
תג בלוק מתחיל בשורה משלו, לאחר רווחים אופציונליים וכוכבית התחלתית אופציונלית. השתמשו בתגית רב-שורתית המוצגת.
הסבר על החלטה שאין לקורא נראית
- הערת הנחה מועילה עשויה לומר “התשלום הוא 90% מהמחיר הרשום; תרגול זה משתמש במחירים שלמים”. הדבר מסביר מדיניות והנחות, בעוד ש-
// multiply by 90פשוט חוזר על פעולה. - סיכום של שיטה ציבורית מועיל גם כאשר הגוף שלה קצר: קוראים זקוקים לחוזה שלה מבלי ללמוד את הא implementation. עדיף הסברים המספקים הקשר חסר במקום להכריז כל הערה תיאורית למיותרת.
כאשר תוכנית Java פועלת, התגובות...
Difficulty 1/5 · 100 coins + a small bonus on first completion today
תגובות הן עבור בני אדם — Java מתעלמת מהן.
מהי התחלה לתגובה שטוחה ב-Java?
Difficulty 1/5 · 100 coins + a small bonus on first completion today
// נמשכת לקצה השורה; /* */ היא בלוק.
איזה סוג של תגובה הכלים ממירים לתיעוד API?
Difficulty 1/5 · 100 coins + a small bonus on first completion today
Javadoc /** */ עם @param/@return מייצר תיעוד API.
הוספת תגית הסבר לצד נוסחה פעילה שאינה השתנתה תתקן את החישוב שלה.
Difficulty 1/5 · 100 coins + a small bonus on first completion today
שגויה: תגיות הסבר הן לא פקודות. ביטול פעולה (commenting out) יכול לשנות התנהגות, אך שינוי זה משנה אילו קודים פעילים.
תגובות טובות מסבירות מדוע, ולא חוזרות על מה שקוד עושה במובן.
Difficulty 1/5 · 100 coins + a small bonus on first completion today
תגב את הכוונה, לא את המובן.
בדוק מסמך מול א implementación
- נתון שההערה מבטיחה שרדיוסים שליליים יידחו, אך המגן נמחק. המסמך הוא כעת שגוי גם שהוא עדיין מייצר בהצלחה; בודק גם קלט שלילי וגם רדיוס רגיל.
- כאשר התנהגות משתנה, עדכן את הא implementation, את הבדיקות ואת המסמך ביחד. יצירת דף API בודק סyntaxis מסמך, לא אמתיות של כל הטענה בו.
/** Returns an area. @param r radius @return area */ לא מניח את תגי הבלוק בתחילת השורות הנדרשות. השתמש בצורת רב-שורתית למעלה, ולאחר מכן בדוק את הא section פרמטר ו-return המוצגים. הערות הסבר רגילות הן לא תיקונים ביצועיים.
האם הערה שימושית או לא?
תגובות טובות מוסרות כוונה, ולא דברים מובנים. סדר כל אחת מהן.
נבא הקצאה שמולכה בהערה
- התחל עם
int x = 1;. עםx = 5;פעיל, הדפסת x תניב 5; החלפת שורה זו ב-// x = 5;תדפיס 1. שינוי אלו פקודות הן פעילות שונה מהוספת הערה לצד פקודה בלתי משתנה. - סקר שלושה שאלות בנפרד: האם החישוב הפעיל נכון, האם ההערה מסבירה אותו באופן מדויק, והאם תגי Javadoc פוענחים לתוך הא sections המיועדים? ריצה מוצלחת אינה עונה על כל שלושתם.
הערות מסבירות קוד לקוראים. תחומי הפרדה יכולים לשלול פקודות, בעוד שהערות לצד קוד פעיל לא מתקנים חישובים. תגי בלוק Javadoc מתחילים בשורות נפרדות; שמור על חוזה מסמך תואם ל-A implementation.
For a price of 100, type the amount paid after a ten percent discount.
Difficulty 1/5 · 100 coins + a small bonus on first completion today
The intended payment is 100−10=90. The misleading comment does not make the original expression calculate 90.
int x = 1; מופעל ולאחריו // x = 5; בשורה נפרדת. מהו הערך של x שהודפס?
Difficulty 2/5 · 140 coins + a small bonus on first completion today
ההטלה ל-5 מופעלת על ידי ההערות השורה אחת; x נשאר 1.