בדוגמה שבתיעוד הזה ל send_message, למשתמשים קוראים a ו-b וההודעה הנשלחת היא “Hello!”. שתי שאלות:
האם נהוג בתיעוד להדגים את הפעולות הבאות במחלקה תוך שימוש באותם ארגומנטים (לצורך העניין a ו-b), או שהיד חופשית והיצירתיות יכולה להשתולל (בגבול הטעם הטוב והמובן)?
האם ניתן בכתיבת הדוגמאות בתיעוד הפעולות הבאות לזנוח את יצירת האובייקט, ולהתחיל ממצב נתון של אובייקטים קיימים (באופן ברור ומוסבר כמובן)? פה אני בעצם שואלת - האם בכתיבת הדוגמה של התיעוד ל- read_inbox כדאי להתחיל את הדוגמה מההתחלה ולפרט את כל השלבים המקדימים (יצירת אובייקט, שליחת x הודעות ליצירת תיבת דואר של משתמש עם x הודעות), או שאין צורך?
תודה לעוזרות והעוזרים
Yam
יצירתיות זה טוב. That being said, זה פשוט צריך להיות מובן לקורא.
ממליץ באופן כללי לחפש ספריות מעניינות (נסי נניח NumPy, Pandas) ולהציץ על התיעוד שלהם. זה יעזור לגבש הרגלים נחמדים. הם רחוקים מלהיות ספר חוקים אבסולוטי אבל יש שם רעיונות מעולים.
יצירת האובייקט היא לרוב שורה אחת. זה מבהיר אילו פרמטרים הוא צריך לקבל, ויש כלים אוטומטיים שכשכותבים תיעוד בפורמט הזה יכולים להשתמש ב־docstring כדי להריץ טסטים ולבדוק שהמחלקה שלך עובדת. הייתי משאיר את אתחול האובייקט.
