תיאור כללי

מעבר על המערכת כדי לנקות את הקוד.

מה ההצעה כוללת?

• תיקון שגיאות ש mypy מדווח
• תיקון שגיאות כתיב
• הוספת TODO איפה שחסר
• ריפקטור של פונקציות שחוזרות על עצמן למקום אחד - לדוגמא, יצירת יוזר פיקטיבי שקיים בלפחות 3-4 מקומות שונים במערכת
• שימוש בfastapi.status איפה שצריך במקום מספרים

כולל שינויים בקוד? אם כן, איפה?

כן. איפה שיהיה צורך.

האם יהיו שינויים במסד הנתונים? אם כן, איפה?

לא.

האם יהיה שינוי ב־frontend? אם כן, איפה?

כן. איפה שיהיה צורך.

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

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

שמעתי מים שיש דעות חלוקות לגבי כתיבת TODO בתוך קוד.
לינק בנושא (ים, שם,שם)

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

• 1 זאת טענה חסרת תוכן.ל IDE כמו PyCharm לדוגמא יש טאב שבו מופיעים כל ה TODO. לא צריך לחפש ידנית בקוד.
• 2 ו3 אלו טענות בלי תוכן
• 4 לא רלוונטית אלינו כי אנחנו לא משתמשים במערכת שמתעדפת תיקונים
• 5 לא רלוונטית אלינו כי אין לנו בוס ואין לנו הספק שאנחנו צריכים לעמוד בו

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

ובאופן משעשע, לאותו מאמר יש גם את המאמר הנגדי

לא מנומס לא לקרוא את המאמר ולהגיד שהוא חסר תוכן

אענה בקצרה ולא אגיב בהמשך כדי להימנע מוויכוח ארוך על משהו שהוא בכ"מ דעה חלוקה:

טענות 2 ו־3 לא חסרות תוכן, ולמעשה מאוד חשובות.
טענה 2 מדברת על שכפול של TODO בכמה מקומות. החסרון המיידי הוא שיכול להיות שיישאר לך TODO בקוד למרות שכבר טיפלת בו.
טענה 3 מדברת על חוסר עדכון של הערות – משהו שאנחנו רואים הרבה (ואחת הטענות החזקות והמרכזיות נגד הערות בקוד) – אנשים מתעלמים מהערות ולא שמים לב שהן נמצאות שם, ההערות לא מתעדכנות ואז יוצא מצב שיש הערות שלא תואמות את הקוד. זה בעייתי כי ישארו issues פתוחים למרות שכבר טיפלו בהן.

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

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

---

בכ"מ הרעיון המקורי באשכול נשמע לי מצוין!

רק לצורך תשובה רשמית, כי כמו שאמרתי, אני יכול גם לא, להוסיף או לא להוסיף הערות TODO?

כיוון שמדובר במשהו שמבוסס על דעה אישית, ואחת שאין לי העדפה סופר חזקה לגביה, בנושא הזה כל אחד יכול לעשות מה שהוא מעדיף (:

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

הערות:

1. ההנחיות של גוגל וההנחיות של PEP 257 קצת סותרות אחד את השני.
   בגוגל כתוב:

   The docstring should be descriptive-style ("""Fetches rows from a Bigtable.""") rather than imperative-style ("""Fetch rows from a Bigtable.""")

בעוד ב PEP כתוב:

The docstring is a phrase ending in a period. It prescribes the function or method’s effect as a command (“Do this”, “Return that”), not as a description; e.g. don’t write “Returns the pathname …”.

לפי איזה סגנון אנחנו פועלים בפרוייקט?

2. בהמשך הסגנון של גוגל כתוב:

The description should include required type(s) if the code does not contain a corresponding type annotation.

מכיוון שאנחנו משתמשים ב type annotation, האם הדוקומנצטיה אצלנו כוללת אותם או לא?

3. בדוגמאות שהם נתנו, אין ציון של הtype בחלק של ה Returns. האם לכלול אותו אצלנו או לא?

4. האם הטקסט אחרי השם הפרמטר והנקודותיים באות גדולה או קטנה?

שמות קבצים:

1. איך נכון לכתוב שמות שמורכבים מיותר ממילה אחת: מילה אחת מחוברת, עם הפרדה בקו תחתון או במקף? לדוגמא: dayview.py, calendar_grid.py ו trash-can.svg (כל אלה קיימים בפרוייקט).

2. האם שמות כל הקבצים צריכים להתחיל באות קטנה? לדוגמא: Aquarius.svg

סגנון פייתון:

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

router = APIRouter(
    prefix="/calendar/month",
    tags=["calendar"],
    responses={404: {"description": "Not found"}},
)

2. האם להוסיף קו תחתון בתחילת שם לפונקציות protected?

סגנון HTML:

1. האם צריך לבצע indent לטקסט בקובץ html אחרי if או for?

2. מה כמות הרווחים בקובץ html? האם אנחנו הולכים לפי גוגל שאומר 2 רווחים ל indent ולפחות 4 בcontinuation? (זה דיי שמושי לסגור כי זה משהו שאפשר להגדיר ב IDE)

3. באיזה סגנון נעשה שימוש לשמות ID, class שמורכבים מיותר ממילה אחת? גוגל אומרים להשתמש במקף. כרגע בפרוייקט יש לנו שימוש בכל סוג אפשרי.

הערות

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

לדעתי השימוש ב־Type Annotations מייתר את הצורך בהכנסת הסוג לתיעוד, זה יהיה שכפול מידע ואנחנו אוהבים DRY

אותה תשובה – לדעתי אין צורך כיוון שזה כלול ב־type annotations

לפי Capitalization After Colons | Grammarly, אם זה משפט שלם חדש אפשר להשתמש ב־Uppercase. נראה לי שזה המצב כאן

---

שמות קבצים

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

הייתי משאיר כמו שזה, כי אתה לא רוצה ללכת לבדוק עכשיו עבור כל קובץ אם זה שם של מישהו ולשנות בהתאם.

סגנון פייתון:

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

אם אתה בטוח מאוד שהן protected

סגנון HTML

להערכתי להזיח (כך ב־docs של Jinja2). אם רוצים להימנע מהגועל שזה גורם ב־HTML אפשר להשתמש ב־whitespace control של Jinja2

כן

בוא נשתמש במקף