
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 במהלך השנים, עבדתי על כל מיני פרויקטים – גדולים, קטנים, כאוטיים, מהונדסים יתר על המידה, "זמניים", מובנים היטב לכאורה, וכל מה שביניהם. ובכל זאת תבנית אחת נשארה עקבית באופן משעשע: התיעוד תמיד חסר, מיושן, או קבור בפינה נשכחת של Confluence הנשמרת על ידי חותמת זמן משנת 2019. כל פרויקט   שיש לו תיעוד. טוען כל צוות   שיעדכן אותו. מבטיח וכל מפתח אומר בביטחון, "אל תדאג, אני אכתוב את זה מאוחר יותר", אשר, כפי שכולנו יודעים, הוא המקבילה התיעודית לומר  "הצ'ק בדרך בדואר". לאחר שצפיתי במחזור הזה חוזר על עצמו יותר פעמים ממה שהייתי רוצה להודות, הבנתי משהו פשוט אך אמיתי באופן אכזרי: 
 
 התיעוד שורד רק אם הוא חי קרוב ככל האפשר לקוד – כי מפתחים (כולל אני) הם יצורים עצלנים. ומכך, הגיעה תובנה נוספת – הבעיה העיקרית עם תיעוד מיושן היא העובדה שרוב הצוותים לא מתייחסים אליו כחלק ממחזור הפיתוח הראשי, משאירים אותו לאחר כך או מסתפקים בכמה מפרטים טרום-פיתוח שהיו להם כבר איפשהו ב-Confluence. כדי לכתוב תיעוד משמעותי, בואו נדון תחילה איזה סוג של תיעוד קיים לרכיב תוכנה: דרכים לתעד קוד (שמפתחים עשויים להשתמש בהן בפועל) ברגע שתקבלו שתיעוד חייב לחיות קרוב לקוד, השאלה הבאה היא   למבנה אותו. כיצד בפועל, מצאתי שתיעוד טוב אינו נכס יחיד – אלא מערכת אקולוגית קטנה של שכבות, כל אחת משרתת מטרה וקהל שונה. עבור אותו פרויקט שהזכרתי (כתוב ב-Java + Spring Boot), זיהינו ארבעה סוגי מסמכים עיקריים: 1. מפרטי לקוח אלו הם מסמכים קונבנציונליים הנערכים בדרך כלל על ידי מומחה תחום. באופן אידיאלי, הם עשירים בשפה אוניברסלית ומספקים תיאורים של מקרי עסקים שאינם תלויים בקוד – במילים אחרות, כל מה שמהנדס צריך כדי להבין באמת את הבעיה העומדת בפניו. למרבה הצער, במציאות, מסמכים אלו מסתיימים לעיתים קרובות מאוחסנים איפשהו ב-Confluence, משותפים עם הצוות בתחילת פרויקט, ואז כמעט אף פעם לא מתעדכנים שוב. אל תבינו אותי לא נכון: מסמכים אלו  . חשובים חילוץ ידע ממומחי תחום צריך להיות בראש סדר העדיפויות של כל צוות הנדסי. אבל מפרטים מתפתחים, לחצי מועדים מלחיצים את כולם, והמסמכים המקוריים הללו הופכים לאט לאט אך בוודאות לבסיס מיושן. הידע על דרישות משתנות, מקרי קצה, ופניות פרויקט מסתיים חי בקוד – או גרוע מכך! – במוחות של מפתחים בכירים. כדי לטפל בזה, הפסקנו לכתוב מפרטים בקבצי Word אקראיים או דפי Confluence המיועדים להישכח והעברנו אותם קרוב ככל האפשר לקו החזית:  מאגר הקוד. התחלנו לאחסן אותם כקבצי Markdown (.md) בתוך המאגר, בדרך כלל בתיקיית docs/. בסביבות מיקרו-שירותים גדולות, מסמכים אלו יכולים אפילו להצדיק מאגר ייעודי המקושר כתת-מודול Git. תת-מודולים נעדרים לעיתים קרובות, אך הם דרך עוצמתית לשמור על סדר במערכות מרובות-מאגרים. לקריאה נוספת על תת-מודולים, אני ממליץ בחום על פוסט זה בבלוג -  . קישור 2. README – הדלת הקדמית לבני אדם אם מפרטי לקוח הם האנציקלופדיה, ה-README הוא הדלת הקדמית. ובכל זאת, זהו אחד מחלקי התיעוד המופקרים ביותר בפרויקטי תוכנה. באופן אירוני, כמעט כל פלטפורמת בקרת גרסאות – GitHub, GitLab, Bitbucket – מציגה באופן אוטומטי את ה-README ישירות בדף הפרויקט הראשי. זה הדבר הראשון שכל מפתח רואה כשהוא נכנס למאגר. למרות זאת, READMEs לעיתים קרובות ריקים באופן מזעזע, מיושנים באופן כואב, או מלאים ב-"TODO: לכתוב תיעוד מאוחר יותר", אשר כמובן לעולם לא קורה. README טוב אינו אופציונלי. זהו המסמך היחיד שהכי סביר שייקרא בפועל מכיוון שהוא דורש  . ומכיוון שהוא יושב בשורש המאגר, מפתחים נוטים יותר לעדכן אותו בזמן העבודה על הקוד. זהו תיעוד שחי בנתיב ההתנגדות המינימלית. אפס קליקים README כתוב היטב צריך לענות על השאלות החשובות ביותר שיש למפתח בדקות הראשונות של מפגש עם פרויקט: 
 
 
 
 
 
 
  הצהרת מטרה והקשר תמציתית - ללא "שיווקי". מה השירות/פרויקט/רכיב הזה עושה? -  הוראות הרצה, משתני סביבה, הגדרת תלויות, וכל פקודה ספציפית לפרויקט. איך אני מריץ אותו מקומית? -  בדיקות יחידה, בדיקות אינטגרציה, הגדרת נתוני בדיקה, וכל כלי הקשור לבדיקות. איך אני בודק אותו? -  הסבר קצר על פריסת הספריות, מודולים מרכזיים, והיכן למצוא את החלקים החשובים של הקוד. איך הפרויקט בנוי? -  סקריפטים פריסה, הערות CI/CD, הרשאות נדרשות, או ניואנסים של פלטפורמה. איך אני פורס אותו?  קישורים לתיעוד שנוצר, הערות ארכיטקטורה, הפניות API, ומסמכי עיצוב מרכזיים. היכן אוכל לקרוא עוד? - ה-README הוא השער לפרויקט. הוא קובע ציפיות, מקצר את זמן ההסתגלות, ונותן לכל מהנדס – חדש או מנוסה – נקודת התמצאות ברורה. כאשר הוא מתוחזק כראוי, הוא הופך למסמך היחיד בעל הערך הרב ביותר בכל המאגר. 3. JavaDocs – תיעוד שהמהדר מציק לך לתחזק JavaDocs – בלתי נראים בדרך כלל, נשכחים לעיתים קרובות, אך חיוניים לחלוטין כאשר משהו נשבר. בפועל, תיעוד פרויקטי Java נוטה לשני קצוות: או  , או   כי "הקוד מתעד את עצמו". האמת, כמו תמיד, נמצאת איפשהו באמצע. הערות יתר על כל שורה טריוויאלית ללא הערות כלל עבור הפרויקט שלנו, עשינו החלטה מודעת לתעד  . זה אומר: רק את מה שהיה הכרחי באמת 
 
 
 
 
 שימוש ב  כך שמסגרות התחום התאימו בדיוק למה שהיה במפרטים העסקיים שפה אוניברסלית הסברת ה  מאחורי החלטות לא ברורות, לא ה  שהקוד כבר חושף למה מה תיעוד מחלקות דומיין מרכזיות, ממשקים, ותהליכים מורכבים הימנעות מקירות הערות שפשוט חוזרים על שם הפונקציה בצורה מפורטת JavaDocs, כאשר משתמשים בהם כראוי, משמשים כתיעוד ברמת המיקרו המבהיר כוונה מבלי לזהם את הקוד. ובניגוד לדפי Confluence, ל-JavaDocs יש יתרון מובנה: 
 
 המהדר באמת מתלונן כשהם יוצאים מסינכרון. אם תשנה שם של פרמטר אך תשכח את תגית ה-JavaDoc, הבנייה תזכיר לך. אם תמחק פונקציה אך תשאיר הפניות הערות עומדות, הסביבה המשולבת תזהר כמו עץ חג המולד. החיכוך העדין הזה הוא בדיוק הסיבה שבגללה JavaDocs נוטים להישאר מדויקים יותר מצורות תיעוד אחרות – הם מעצבנים להזניח. כדי לשמור על הכל מרכזי ולהימנע מ"איי תיעוד", השתמשנו גם ב . Doxygen Doxygen הוא כלי נפוץ ליצירת תיעוד בפיתוח תוכנה. בעוד שהוא משמש בעיקר בקהילת C++, השתמשנו בו כדי לאגד את ה-JavaDocs לייחוס עקבי וניתן לגלישה – דף HTML. יש לו מספר תכונות ש-JavaDoc אינו מציע, למשל, דיאגרמות מחלקות עבור ההיררכיות והקשר שיתוף הפעולה, יותר דפי סיכום, ועוד רבים. זה נתן לנו תצוגה נקייה ומאוחדת של כל בסיס הקוד מבלי להסתמך על רמזי IDE מפוזרים. 4. קוד נקי – התיעוד שאתה לא צריך לתחזק לבסוף, הצורה הכי מוערכת חסר של תיעוד היא גם זו שמפתחים מכבדים הכי פחות עד שהם באמת צריכים אותה:  קוד נקי. הערות מזדקנות. מפרטים מתרחקים. READMEs מוזנחים. JavaDocs יכולים להתיישן. אך קוד כתוב היטב – ברור, מכוון, וביטוי –   תיעוד. הוא כפי שאמר דוד בוב המפורסם,  "קוד נקי נקרא כמו פרוזה כתובה היטב." ובפועל, זה אומר: 
 
 
 
 
 
 
 מחלקות ופונקציות עם שמות שחושפים את מטרתן פונקציות שעושות דבר אחד ועושות אותו טוב טרמינולוגיית תחום המשמשת באופן עקבי לאורך כל הדרך אין חוכמה למען החוכמה אין "התנהגויות מפתיעות" מוסתרות בתוך תופעות לוואי אין הפשטות עמוקות שלא לצורך הדורשות דוקטורט להבין קוד נקי הוא הנכס היחיד המובטח לשרוד רפקטורינג, ספרינטים, תחלופת צוות, וכאוס ארגוני. הוא תמיד מסונכרן עם התנהגות המערכת כי – הוא   התנהגות המערכת. הוא כלל פשוט עלה לאורך זמן:  אם אתה צריך פסקה של הערות כדי להסביר פונקציה, הבעיה האמיתית היא הפונקציה. כשהקוד ביטוי, כל השאר הופך לקל יותר → JavaDocs הופכים קלים וממוקדים יותר → ה-README מצטמצם כי ההסתגלות הופכת ברורה → מפרטים הופכים ברורים יותר כי הדומיין מודל משקף את אוצר המילים העסקי. קוד נקי לא מבטל את הצורך בתיעוד; הוא   אותו. מעגן הוא מבטיח שכל צורות התיעוד האחרות – מפרטים, READMEs, JavaDocs – מחזקות את האמת במקום לפצות על יישום לא ברור. בסופו של דבר, קוד נקי הוא התיעוד שאינו דורש תחזוקה, אינטגרציית CI, או כלים. זוהי ההסבר הכי כנה ואמין למה שהמערכת באמת עושה. איסוף הכל ביחד – צינור תיעוד חי לאחר ששיפרנו כיצד כתבנו תיעוד, השלב האחרון היה להבטיח שהוא לא רק נוצר – אלא נמסר באופן רציף ונגיש תמיד. לשם כך, בנינו צינור תיעוד שהפך את המפרטים שלנו, קבצי README, ו-JavaDocs לפורטל   יחיד ומאוחד. תיעוד חי מכיוון שרצינו שהתיעוד שלנו יחיה קרוב ככל האפשר לקוד שלנו, החלטנו לפרוס הכל דרך  , שסיפק לנו פתרון אירוח ללא מאמץ, מבוקר גרסאות, הקשור ישירות לבסיס הקוד. Github Pages אינו ייחודי ל-Github (ל-GitLab, למשל, יש גם GitLab pages) – זוהי עוד תכונה נחמדה של מערכות בקרת הגרסאות הפופולריות שאני ממליץ לקריאה נוספת –  . GitHub Pages קישור כדי לקמפל הכל לסט של דפים קוהרנטיים, השתמשנו ב Sphinx. Sphinx הוא מחולל תיעוד עוצמתי כתוב בפייתון. הוא לוקח קבצי מקור כתובים ב-reStructuredText או Markdown ומתרגם אותם לפורמטים פלט שונים, כולל HTML, PDF, ו-ePub. Sphinx טיפל במבנה, ניווט, ועיצוב. Doxygen האכיל את Sphinx עם JavaDocs שנוצרו אוטומטית באמצעות תוסף  , מה שנתן לנו הפניית API הניתנת לגלישה מלאה ישירות מקוד המקור. בינתיים, ה-README הראשי שימש כנקודת הכניסה המיידית למפתחים החוקרים את המאגר, המקושרת בצורה חלקה לאתר התיעוד שנוצר. Breathe כל מיזוג ל-main הפעיל משימת CI שבנתה מחדש את התיעוד, מה שמבטיח שהפורטל שיקף את שינויי הקוד האחרונים, עדכוני API, והחלטות עיצוב. שום דבר לא חי בבידוד. שום דבר לא דרש סנכרון ידני. וחשוב מכך – שום דבר לא היה יותר מקליק אחד. זה הפך את התיעוד שלנו מנכס סטטי למערכת אקולוגית מתעדכנת באופן רציף שמפתחים השתמשו בה בפועל, מכיוון שהוא שולב ישירות בזרימת העבודה היומיומית שלהם וחי לצד הקוד. מסקנה – תיעוד הוא האחריות שלנו, לא הנטל שלנו בסופו של יום, כתיבת תיעוד אינה אופציונלית. זה חלק מהעבודה שלנו כאנשי מקצוע הנדסיים. עמיתים עתידיים תלויים בו. הסתגלות תלויה בו. תחזוקה, אמינות, ואפילו בהירות ארכיטקטונית תלויות בו. אבל קבלת האחריות הזו לא אומרת שתיעוד צריך להיות כואב. על ידי שמירת תיעוד קרוב לקוד, אוטומציה של כל מה שניתן לאוטומציה, והסתמכות על כלים חכמים כמו Markdown, JavaDocs, Doxygen, ו-Sphinx, אנו מסירים את החיכוך שבדרך כלל הורג מאמצי תיעוד. אנו הופכים משהו שבאופן מסורתי מרגיש כמו מטלה להרחבה טבעית של פיתוח יומיומי. וכאשר אנו משלבים זאת עם קוד נקי, READMEs טובים, ומפרטים עשירים בדומיין, כל המערכת האקולוגית הופכת למתקיימת מעצמה. תיעוד לא צריך להיות מושלם – הוא פשוט צריך להיות נגיש, מדויק, וחי. כאשר אנו בונים מערכות המעודדות מפתחים לעדכן תיעוד בקלות כפי שהם כותבים קוד, כולם מרוויחים: הצוות, המוצר, והכי חשוב, הנשמה הענייה שתירש את הפרויקט שישה חודשים מאוחר יותר. תיעוד טוב לא הופך אותנו לפחות עצלנים. זה פשוט הופך להיות עצלן תואם לבניית תוכנה נהדרת.

The is an opinion piece based on the author’s POV and does not necessarily reflect the views of HackerNoon.

Read My Stories

האודיו הזה מופק בשפת המקור של הסיפור!

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

About Author

הערות

תלו תגים

מאמר זה הוצג ב

Related Stories

The TechBeat: Investigating Internet Freedom: Unseen Aspects of Our Online Existence (1/20/2024)

The TechBeat: Python's Testing Playbook: Building Bulletproof Code (1/18/2024)

ברכות עונות מ-HackerNoon: Boost Stories עם תרגומים, דיבור לטקסט ועוד

The TechBeat: To Focus or Not Focus: How to Find the Right Product-Market Fit (3/14/2024)

The TechBeat: Investigating Internet Freedom: Unseen Aspects of Our Online Existence (1/20/2024)

The TechBeat: Python's Testing Playbook: Building Bulletproof Code (1/18/2024)

ברכות עונות מ-HackerNoon: Boost Stories עם תרגומים, דיבור לטקסט ועוד

The TechBeat: To Focus or Not Focus: How to Find the Right Product-Market Fit (3/14/2024)

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps