המדריך לדיגום פרוייקטים

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

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

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

אני מניח שבשלב הזה יישמת כמה שיותר מהטיפים מהפוסט הקודם:

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

בנוסף לדברים הנ"ל, כדאי לוודא ש:

• אין שגיאות איות מביכות באנגלית בשמות המשתנים והפונקציות. זאת נקודה חשובה, ובמידת הצורך, בהחלט כדאי להיעזר בחברה ששולטת היטב באנגלית. [1]
  עדכון, ותודה לידיד הבלוג ברוך: סביבות הפיתוח של JetBrains זמינות בחינם לסטודנטים, ומאפשרות להתקין plugins של בדיקת איות. לא ניסיתי, ואני לא בטוח איך זה עובד עם שמות בשיטת CamelCase, אבל שווה לנסות.
  
• שמות המודולים והפונקציות נבחרו באופן סביר (ולכל הפחות, ניכר שנעשה מאמץ מינימלי לבחור שם קריא, ולא שם בסגנון my_func). כמובן שממש לא כדאי להעלות קוד שלא מקיים את התנאי הזה.
• אם את מכירה מתכנתת שכבר עובדת בתעשיה, ויכולה לבקש ממנה להסתכל על הקוד (מה שנקרא code review), זה כמובן יכול לתרום המון. אם את לא מכירה, אפשר להסתדר גם בלי 🙂

עמוד הפרוייקט

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

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

מה הפרוייקט עושה

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

היסטוריית commits

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

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

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

הוראות קומפילציה

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

• על איזה מערכות הפעלה קימפלת בהצלחה. הניסוח המקובל הוא כנראה משהו בסגנון
• Compiles successfully on Ubuntu-16.78. Should also compile on other linux variants, with some hand holding. Other operating systems are currently not supported.
• לכל אחת מאותן מערכות הפעלה, איך אמורים לקמפל. אם יש לך את הזמן, כדאי לעשות מאמץ סביר לוודא שהוראות הקימפול הללו אכן עובדות במחשב נוסף, לא רק על המחשב שלך.
• באיזה ספריות חיצוניות הפרוייקט משתמש. במידת האפשר, כדאי לצרף גם הוראות התקנה לספריות הללו, למשל
• On Ubuntu: sudo apt-get install bla bli blu
• במידת האפשר, כדאי ליצור קובץ Docker, על מנת לפתור מראש כמה שיותר בעיות תלויות וכו'.
• אם יש אפשרות להעלות אתר לדוגמה שמריץ את הקוד של הפרוייקט, זה כמובן מבורך. במצב הזה, כדאי ללנקק לאתר גם ישירות מקורות החיים, לא רק מעמוד הפרוייקט.

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

העמוד שלך ב-GitHub

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

לשמחתי נתקלתי בדוגמה מוצלחת – שימי לב שהעמוד כולל:

• תמונת פרופיל (למרות שזה לא חובה, ומי שלא מרגישה עם זה בנוח – באמת לא קריטי).
• קווים לדמותו של המפתח, במשפט מתחת לתמונת הפרופיל.
• מספר פרוייקטים ספורים שהמפתח בחר בקפידה להציג בעמוד הראשי שלו, מתוך הrepositories שהוא תרם להן (אין מה להגיד, הבחור הזה רציני, ותרם ל-150 repositories; זאת ממש לא הרמה של בוגר טיפוסי בארץ, אלא הרבה מעבר לכך, כך שאין מה להשוות מולו ולהילחץ).
• כל פרוייקט כולל גם הסבר במשפט.

זהו בינתיים 🙂 נתראה בפעם הבאה.

[1] באופן מפתיע, נראה שאין כלי spell checking לקוד שתפסו. לדעתי לא יהיה קשה לבנות כלי בסיסי כזה שמבוסס על regular expressions ועובד סביר 'אם מחזיקים לו את היד' [2]. האם יש בין הקוראות מישהי שרוצה לבנות את הכלי הזה לטובת הכלל? לדעתי אפשר בכמה שעות ליצור גירסה ראשונית. אוכל לתרום את הסקיצה שיש לי בראש לגבי מבנה הכלי, ולייעץ פה ושם.

[2] כן, כן. אני יודע…

הפוסט פורסם לראשונה [3] באתר של הבלוג ב-The Marker.

[3] הכותרת ותת-הכותרת שעלו בדהמרקר נכתבו ע"י המערכת, ולא על ידי. להערכתי, יש הן מכללות והן מוסדות לא אוניברסיטאים אחרים (שאין להם את המלה "מכללה" בשם) בעשיריה הראשונה של המוסדות בארץ.