תיעוד... תיעוד... תיעוד....

[rontech]

תיעוד... תיעוד... תיעוד....

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

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

 

[hadooper]

...

הדרך היעילה ביותר היא לבצע מעקב ולדאוג שתמיד תהינה "ידיים אחראיות" לכל פרוייקט או קוד. כלומר, אם למפתח מסויים יש על פרוייקט מסויים ownership והוא עוזב מחר את החברה, לדאוג שיחפוף לפני-כן מפתח אחר שיחליף אותו.
&nbsp
בתיעוד ראוי להשתמש רק עבור תשתיות שהשימוש שלהן מאד נפוץ בארגון, API-ים למיניהם (עבור REST אני משתמש ב Swagger) וכד'. עד היום לא מצאתי צורך לתעד כל רכיב או פונקציה.

 

[nahsh]

פתרונות חלקיים

אתרי וויקי למניהם יכולים לעזור, בתנאי שמשתמשים בהם בכלל. בgithub מאוד נח להשתמש בREADME שלהם, ואז זה ממש חלק מהקוד,וגם קריא כמו מסמך.

אבל שום דבר לא יחליף ownership

 

[ai21]

מתחילים בתיעוד API

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

 

[BravoMan]

מתחילים מכתיבת קוד שמתעד את עצמו:

שמות משמעותיים וברורים למחלקות, מתודות, משתנים וכו'.
היררכיות ומבנים הגיוניים ונוחים למעקב.
&nbsp
דברים כמו פרוטוקולי תקשורות מתעדים במסמכים ספציפיים ושומרים אותם במקום רלוונטי כולל ב-source control אם צריך.