איך שומרים על קוד נקי ומאורגן בפרויקט אמיתי

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

מבנה תיקיות שהגיוני מהיום הראשון

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

project/
    src/           # קוד המקור
    tests/         # בדיקות
    docs/          # תיעוד
    .gitignore
    README.md
    requirements.txt

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

שמות שאומרים משהו

x, data, temp, foo - שמות משתנים ופונקציות כאלה עובדים מבחינה טכנית, אבל לא אומרים כלום למי שקורא את הקוד, כולל לכם עצמכם בעוד חודש. שם משתנה טוב מסביר בעצמו מה הוא מכיל, בלי צורך בהערה נוספת:

# פחות טוב
x = get_data()

# הרבה יותר טוב
active_users = get_active_users()

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

פונקציות קטנות עם תפקיד אחד

פונקציה שעושה חמישה דברים שונים קשה להבין, קשה לבדוק, וקשה לתקן בלי לשבור משהו אחר. פונקציה שעושה דבר אחד ברור, עם שם שמתאר בדיוק מה היא עושה, קלה לקרוא, קלה לבדוק בנפרד, וקלה לשנות בלי לפחד מנזק לצד. אם אתם מוצאים את עצמכם כותבים פונקציה שדורשת הערה כדי להסביר "קודם היא עושה X, ואז Y, ואז Z" - זה סימן חזק שכדאי לפצל אותה.

README שבאמת עוזר

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

gitignore מוגדר מההתחלה

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

תלויות מתועדות, לא רק מותקנות

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

commits קטנים שמספרים סיפור

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

עקביות חשובה יותר מ"נכון"

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

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

התחילו את קורס התכנות הבסיסי כאן

לסיכום

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

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

הצטרפו לקהילה בדיסקורד