הפסקת קפה מס' 20. מהו קוד מדור קודם וכיצד לעבוד איתו. כלים המקלים על כתיבת תיעוד טכני

מהו קוד מדור קודם וכיצד לעבוד איתו

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

תכונות מדור קודם

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

• עם טכנולוגיה מיושנת;
• ארכיטקטורה הטרוגנית;
• היעדר או אפילו היעדר מוחלט של תיעוד.

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

1. אנחנו לא יכולים לזלזל במערכת שמגלגלת מיליונים או שניגשים אליה אלפי אנשים ביום. לא משנה כמה זה נכתב גרוע, הקוד המגעיל הזה שרד לייצור ועובד 24/7.

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

הנדסה הפוכה

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

אל תכתוב את הקוד מחדש

הדבר החשוב ביותר בתהליך הפיתוח הוא להרביץ לעצמך בזמן ולא לנסות לשכתב את כל הקוד מאפס. הערך כמה שנות אדם זה ידרוש. לא סביר שהלקוח ירצה להוציא כל כך הרבה כסף על חידוש משהו שכבר עובד. זה חל לא רק על המערכת כולה, אלא גם על כל חלק ממנה. כמובן שהם עשויים לתת לך שבוע להבין הכל, ועוד שבוע לתקן משהו. אבל לא סביר שיתנו לך חודשיים לכתוב שוב חלק מהמערכת. במקום זאת, יישם את הפונקציונליות החדשה באותו סגנון כמו שאר הקוד. במילים אחרות, אם הקוד ישן, אל תתפתו להשתמש בטכנולוגיות חדשות ויפות: אז יהיה קשה מאוד לקרוא קוד כזה. לדוגמה, אתה עלול להיתקל במצב כמו שהיה לנו: חלק מהמערכת כתוב ב-Spring MVC, וחלק כתוב בסרבלטים חשופים. ואם בחלק שנכתב בסרבלטים צריך להוסיף עוד משהו, אז נוסיף אותו באותו אופן - בסרבלטים.

כבד את האינטרסים העסקיים

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

מִבְחָן

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

1. אימות, כאשר הפונקציונליות המיושמת של תכונה מסומנת בענף נפרד.
2. ייצוב, כאשר בודקים ענף שחרור בו כל התכונות מתמזגות יחד.
3. הסמכה, כאשר אותו דבר מופעל שוב על מקרי בדיקה מעט שונים בסביבת הסמכה הקרובה ככל האפשר לייצור מבחינת מאפייני החומרה והתצורה.

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

רשמי DevOps ושחרר

הליך השחרור יכול, למשל, להיות כדלקמן. כאשר הפיתוח הושלם והושלמו שניים או שלושה שלבי בדיקה, אנו כותבים דוא"ל לצוות DevOps 36 שעות לפני מועד השחרור הצפוי. לאחר מכן, אנו מתקשרים לצוות devops ודנים בכל השינויים בסביבות (אנו מודיעים להם על כל השינויים במסד הנתונים ובתצורה). לכל שינוי יש לנו מסמך (כרטיס בג'ירה). ואז, במהלך השחרור, כל המעורבים בזה מתכנסים, וכולם אומרים מה הם עושים עכשיו: "העלינו את מסד הנתונים", "הפעלנו מחדש שרתים כאלה ואחרים", "הלכנו להריץ מבחני רגרסיה בסביבת הייצור. ” אם משהו משתבש, יוצא לדרך הליך השחרור לאחור, המתואר בדיוק במסמך השחרור המקורי – ללא מסמך כזה בהחלט נשכח משהו או נתבלבל.

איכות קוד בקרה

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

כלים המקלים על כתיבת תיעוד טכני

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

דפי GitHub

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

קרא את המסמכים

כפי שהשם מרמז, Read the Docs מספקת למפתחים פלטפורמה לאחסון וקריאת תיעוד. השירות עובד בדומה ל-GitHub Pages: מתכנתים יכולים לבצע שינויים בתיעוד ממערכות בקרת הגרסאות המועדפות עליהם, כולל Git, Bazaar, Mercurial ואחרות. ניהול גרסאות אוטומטי ויצירת דפים נתמכים גם. החלק הטוב ביותר של Read Docs הוא הגמישות שלו. הוא תומך ב-webhooks כך שתוכל להפוך חלק גדול מתהליך יצירת המסמכים לאוטומטי. זהו חיסכון עצום בזמן במשימה שרוב המתכנתים לא רוצים שום קשר איתה. בנוסף, כל מה שמתארח בפלטפורמה זמין לקהל הרחב במגוון פורמטים, כולל PDF, HTML של עמוד בודד ואפילו פורמט של ספר אלקטרוני. השירות לוקח על עצמו חלק נכבד מהעבודה השוטפת על מנת לעדכן את התיעוד.

טטרה

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

מִכוֶרֶת

מה שהופך את Apiary לכל כך שימושי עבור מפתחים היא העובדה שהיא עושה עבודה נהדרת בסיוע בתיעוד API. הפלטפורמה מאפשרת למשתמשים לכתוב את התיעוד שלהם ב- Markdown , כולל קריאות API מדומות. Apiary גם מאפשר לך לבדוק רכיבי API ואב-טיפוס. במילים אחרות, זהו כלי תיעוד ופלטפורמת בדיקה במקום אחד.