אני מתכבד לפתוח את הנושא ולהעלות מהגיגי, למרות שאף אחד לא הזמין אותי..
להבנתי הקלושה, להערות יש 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
}
בדוגמא הנ"ל, אם צריך לעשות איזה מניפולציה על הפרמטר כדי להגיע לתוצאה הרצויה, מומלץ וטוב להוסיף הערה, אבל שההערה לא תסביר מה עושה השורת קוד הזו, כי זה צריך להיות מובן מתוך הקוד עצמו, אלא שההערה תסביר למה צריך לעשות את מה שהיא עושה.
המשך אולי יבוא. כל המוסיף מוסיפים לו.
הערות יתקבלו בברכה, כולל כל סוגי ההערות
