הערות בקוד - סיעור מוחות
-
אני מתכבד לפתוח את הנושא ולהעלות מהגיגי, למרות שאף אחד לא הזמין אותי..
להבנתי הקלושה, להערות יש 2 מטרות:
- תיעוד, איך משתמשים, איך מתממשקים, איזה פרמטרים להעביר, ומה מקבלים בחזרה, מה הכרחי ומה אופציונלי, וכן על זה הדרך.
- להסביר למה נצרך הקוד, למה הוא חיוני לזרימה של הקוד.
הערה שנועדה להסביר מה הקוד עושה, בעיני זה דבר פסול, הקוד אמור להסביר את עצמו, אם הוא צריך הערות שיסבירו מה הוא עושה זה אומר שהוא לא כתוב נכון.
לדוגמא, פונקציה כזו:// calculate distance // a = begin // b = end function dis(a, b){ return b - a }היא עבירה, וההערה שמסבירה מה היא אמורה לעשות לא מתקנת אותה
פונקציה תקינה אמורה להראות כך:
function calculateDistance(begin, end){ return end - begin }במצב כזה, הערה יכולה לתרום כתיעוד על הפרמטרים שהפונקציה מצפה לקבל, ומה היא מחזירה, וכך עורך הקוד יעזור וימנע טעויות
/** * * @param begin {number} * @param end {number} * @returns {number} */ function calculateDistance(begin, end){ return end - begin }
בדוגמא הנ"ל, אם צריך לעשות איזה מניפולציה על הפרמטר כדי להגיע לתוצאה הרצויה, מומלץ וטוב להוסיף הערה, אבל שההערה לא תסביר מה עושה השורת קוד הזו, כי זה צריך להיות מובן מתוך הקוד עצמו, אלא שההערה תסביר למה צריך לעשות את מה שהיא עושה.
המשך אולי יבוא. כל המוסיף מוסיפים לו.
הערות יתקבלו בברכה, כולל כל סוגי ההערות -
@יוסף-בן-שמעון אמר בהערות בקוד - סיעור מוחות:
הערה שנועדה להסביר מה הקוד עושה, בעיני זה דבר פסול, הקוד אמור להסביר את עצמו, אם הוא צריך הערות שיסבירו מה הוא עושה זה אומר שהוא לא כתוב נכון.
תודה רבה על היוזמה.
לענ"ד המשפט למעלה לא נכון.
יש פונקציות מסובכות, מה לעשות.
פונקציה אמורה להיות קצרה ופשטנית, אבל לא תמיד היא כזאת.
ולכן טוב שיהיה גם הסבר מה הפונקציה הזו עושה (אם כתוב מה היא מחזירה, מספיק. ואת זה גם אתה אמרת).חוץ מזה, הכל נכון (שוב, לדעתי).
אגב, יש מוסכמות בעניין כתיבת הערות?
ואם כן - יש איזה לינטר שאוכף אותן? -
-
תגידו -
עם כל הטירוף הזה של המשתנים והפונקציות,
בסוף זה לא משפיע על המהירות?כמה זמן לוקח השמה של משתנה?
אני כן מנסה לחתור לזה,
אבל הפוסט הזה@nigun אמר בהערות בקוד - סיעור מוחות:
פוסט של ליאור בר און על קוד ספרותי
כבר נראה לי מוגזם...
הוא משבש את התחביר הנורמלי של הקוד, כדי שיהיה יותר ברור!
(פונקציית הSWITCH שם).זה בסוף לא עולה מחיר?
-
@MusiCode
זה לא עולה מחיר, מפני שבסופו של דבר קוד המכונה מקומפל לאותו דבר
זה כן עושה את הקוד קריא יותררוב המאמר המוחלט שם נסמך על מה שנכתב בנושא בספר Code Complete שהוא אחד מרבי המכר למתכנתים שכבר אוחזים שנים בתחום
והנה הגירסה העברית המקוצרת מעט שלו
https://www.hod-ami.co.il/files/59460.pdfשווה כל שקל, ואני ממש
שלא קראתי את הספר הזה בשלב מוקדם יותר של חיי התיכנותיים.הספר לא מוגבל לשפה מסויימת, ובעיקר מכיל עקרונות מפתח לתיכנון ופיתוח נכון.
לדוגמא לגבי המשתנה i בלולאת for, יש בספר דיון לגבי זה, והמסקנא שככל שהסקופ יותר קטן, אין מניעה להשתמש בi, בעיקר מפני שהוא מוסכמה בינ"ל בנושא בין מתכנתים.
אבל לדברי הספר, ככל שהסקופ של הלולאה יותר גדול, עדיף לתת שם יותר ממשי שיהיה ברור על מה מדובר בתוך הקוד.אחד הדברים המרתקים שלקחתי מהספר, הוא המרחק בין ההגדרה של משתנה לשימוש בו, שווה לכתוב על זה מתישהוא
ואם כבר דיברנו על כתיבה ספרותית, יצא לי לקרוא בעבר קוד של @magicode - תאמינו לי זה כמו לקרוא סיפור מתח עם עלילה גם בלי הערות
-
-
