קוד המקור תגובה טיפים סגנון ושיטות מומלצות

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

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

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

סגנונות תגובה: סקירה כללית

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

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

Inline תגובה

כמעט כל שפת תכנות אחת מציעה inline הערות. אלה מוגבלים לתוכן בשורה אחת ורק להגיב על הטקסט לאחר נקודה מסוימת. כך למשל ב- C / C + + אתה מתחיל תגובה מוטבעת כך:

// התחל משתנה הרישום var myvar = 1; ... 

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

אם (callAjax ($ params)) / בהצלחה להפעיל callAjax עם פרמטרים של משתמש ... קוד

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

בלוקים תיאוריים

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

/ ** * @desc פותח חלון מודאלי להצגת הודעה * $ @ string string $ msg - ההודעה שתוצג * @return bool - הצלחה או כשל * / function modalPopup ($ msg) ... 

מעל הוא דוגמה פשוטה של ​​תגובה תיאורית. כתבתי פונקציה כביכול ב- JavaScript שנקרא modalPopup אשר לוקח פרמטר אחד. את ההערות לעיל השתמשתי תחביר דומה phpDocumentor שבו כל שורה היא קדמה עם @ סמל ואחריו מקש נבחר. אלה לא הולכים להשפיע על הקוד שלך בכל דרך שהיא, אז אתה יכול לכתוב @תיאור במקום @desc ללא כל שינוי.

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

קבוצה / הערות בכיתה

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

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

* * * @desc מחלקה זו תחזיק פונקציות עבור אינטראקציה עם המשתמש * דוגמאות כוללות user_pass (), user_username (), user_age (), user_age (), user_regdate () * @ המחבר ג'ייק Rocheleau [email protected] * @required settings.php * / מופשט בכיתה myWebClass  

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

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

קוד הקדמי קוד תגובה

עכשיו אחרי שאנחנו מכוסים 3 תבניות תגובה חשוב, בואו נסתכל על כמה דוגמאות אחרות. יש מפתחי Frontend רבים שעברו מ HTML סטטי לתוך jQuery ו CSS קוד. הערות HTML אינן תכליתיות בהשוואה ליישומי תכנות, אך כאשר אתה כותב ספריות סגנונות וסקריפטים של דף, הדברים יכולים להיות מבולבלים לאורך זמן.

JavaScript עוקב אחר שיטה מסורתית יותר של הערות הדומות ל- Java, PHP ו- C / C++. CSS רק מנצל את הבלוק בסגנון הערות מסומן על ידי קו נטוי ו כוכבית. אתה צריך לזכור כי הערות יוצגו בגלוי המבקרים שלך, שכן לא CSS ולא JS מנותח בצד השרת, אבל אחת השיטות האלה עובד נהדר עבור השארת מידע tidbits בקוד שלך לחזור על.

באופן ספציפי לשבור את קבצי CSS יכול להיות מטלה. כולנו מכירים את השארת תגובה מוטבעת כדי להסביר תיקון עבור Internet Explorer או Safari. אבל אני מאמין CSS commenting ניתן להשתמש ברמה jQuery ו PHP להשתמש בהם. בואו להתעמק ביצירת קבוצות סגנון לפני נגיעה על כמה טיפים מפורטים עבור הערות קוד.

קבוצות סגנון CSS

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

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

• @resets - לקחת משם שולי דפדפן ברירת המחדל, ריפוד, גופנים, צבעים, וכו '.
• @ גופנים - פסקאות, כותרות, בלוקים, קישורים, קוד
• @ ניווט - קישורים מרכזיים הליבה באתר
• @layout - עטיפה, מיכל, sidebars
• @header & @footer - עשויים להשתנות בהתאם לתכנון שלך. סגנונות אפשריים כוללים קישורים ורשימות לא מסודרות, עמודות תחתונה, כותרות, תת-ניווט

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

/ ** @group footer * / #footer styles ...

/ ** קבוצה תחתונה, גופנים קטנים, עמודות, קישורים חיצוניים ** / 

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

4 טיפים לעיצוב תגובה טובה יותר

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

1. שמור הכל קריא

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

פונקציה getTheMail () קוד כאן יבנה דואר אלקטרוני / קוד הפעלה אם שלנו אישית sendMyMail () שיחה הפונקציה מחזירה נכון למצוא sendMyMail () ב / libib/mailer.class.php אנו בודקים אם המשתמש ממלא את כל השדות ההודעה נשלחת! * / if (sendMyMail ()) return true; / / לשמור נכון ולהציג על המסך הצלחה

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

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

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

2. להקל על כמה שטח!

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

$ dir1 = "/ home /"; // להגדיר את ספריית הבית הראשי $ myCurrentDir = getCurDirr (); // להגדיר את ספריית המשתמש הנוכחית $ userVar = $ get_username (); // שם המשתמש הנוכחי של המשתמש

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

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

Hide (); / / להסתיר תת ניווט על pageload / ** לבדוק עבור אירוע לחץ על עוגן בפנים. ITM div למנוע את הקישור ברירת המחדל פעולה כך שהדף לא ישתנה בגישת קליק אלמנט ההורה של .itm ואחריו רשימת .sub הבאה כדי להחליף / לפתוח ** / $ ('itm a.) live (' click ', function (e ) (.) הבא (). (הבא) (.) ().

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

3. הערה בעת קידוד

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

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

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

4. התמודדות עם שגיאות באגי

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

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

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

סיכום

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

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