תרגיל - יצירת הערות קוד יעילות

  • 13 דקות

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

מהי הערת קוד?

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

// This is a code comment!

ייתכן שמצב זה לא יהיה שימושי בהתחלה, אך הוא שימושי בשלושה מצבים:

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

הערה

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

הכנת סביבת הקידוד שלך

מודול זה כולל תרגילים שמדריכים אותך לאורך התהליך של בנייה והפעלה של קוד לדוגמה. מומלץ להשלים פעילויות אלה באמצעות Visual Studio Code כסביבת הפיתוח שלך. השימוש ב- Visual Studio Code עבור פעילויות אלה יעזור לך לכתוב ולבצע קוד בצורה נוחה יותר בסביבת מפתחים המשמשת מומחים ברחבי העולם.

  1. פתח את Visual Studio Code.

    באפשרותך להשתמש בתפריט ההתחלה של Windows (או במשאב שווה ערך עבור מערכת הפעלה אחרת) כדי לפתוח את Visual Studio Code.

  2. בתפריט קובץ קוד של Visual Studio, בחר פתח תיקיה.

  3. בתיבת הדו-שיח פתיחת תיקיה, נווט אל תיקיית שולחן העבודה של Windows.

    אם יש לך מיקום תיקיה אחר שבו אתה שומר פרוייקטים של קוד, באפשרותך להשתמש במיקום תיקיה זה במקום זאת. להדרכה זו, הדבר החשוב הוא שיהיה לך מיקום שקל לאתר ולזכור.

  4. בתיבת הדו-שיח פתיחת תיקיה, בחר בחר תיקיה.

    אם אתה רואה תיבת דו-שיח של אבטחה השואלת אם אתה נותן אמון בעורכים, בחר כן.

  5. בתפריט מסוף קוד Visual Studio , בחר מסוף חדש.

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

    C:\Users\someuser\Desktop>

    הערה

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

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

    dotnet new console -o ./CsharpProjects/TestProject

    פקודה זו של .NET CLI משתמשת בתבנית של תוכנית .NET כדי ליצור פרוייקט יישום חדש של מסוף C# במיקום התיקיה שצוין. הפקודה יוצרת עבורך את התיקיות CsharpProjects ו- TestProject, ומשתמשת ב- TestProject כשם .csproj הקובץ.

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

  7. בתצוגת EXPLORER, הרחב את התיקיה CsharpProjects .

    אתה אמור לראות את התיקיה TestProject ושני קבצים, קובץ תוכנית C# בשם Program.cs וקובץ פרוייקט C# בשם TestProject.csproj.

  8. בתפריט קובץ קוד של Visual Studio, בחר פתח תיקיה.

  9. בתיבת הדו-שיח פתיחת תיקיה, בחר את התיקיה CsharpProjects ולאחר מכן בחר בחר תיקיה.

  10. בתצוגת EXPLORER, הרחב את התיקיה TestProject ולאחר מכן בחר Program.cs.

  11. מחק את שורות הקוד הקיימות.

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

  12. סגור את לוח המסוף.

יצירת הערות קוד והשימוש בהן

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

  1. בלוח Visual Studio Code Editor, הזן את הקוד הבא:

    string firstName = "Bob";
int widgetsSold = 7;
Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");

  2. כדי לשנות את הקוד עם הערות קוד ותיקונים, עדכן את הקוד באופן הבא:

    string firstName = "Bob";
int widgetsPurchased = 7;
// Testing a change to the message.
// int widgetsSold = 7;
// Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

  3. קח דקה כדי לסקור את ההערות ואת עדכוני הקוד שלך.

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

  4. בתפריט קובץ קוד של Visual Studio, לחץ על שמור.

  5. בתצוגת EXPLORER, כדי לפתוח מסוף במיקום התיקיה TestProject, לחץ באמצעות לחצן העכבר הימני על TestProject ולאחר מכן בחר פתח במסוף משולב.

  6. בשורת הפקודה של מסוף, הקלד dotnet run ולאחר מכן הקש Enter.

    אתה אמור לראות את הפלט הבא:

    Bob purchased 7 widgets.

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

  7. מחק את הערות הקוד.

    הקוד שלך אמור להתאים לפריטים הבאים:

    string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

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

    /*
string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
*/

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

  9. החלף את הקוד הקיים שלך בפעולות הבאות:

    Random random = new Random();
string[] orderIDs = new string[5];
// Loop through each blank orderID
for (int i = 0; i < orderIDs.Length; i++)
{
    // Get a random value that equates to ASCII letters A through E
    int prefixValue = random.Next(65, 70);
    // Convert the random value into a char, then a string
    string prefix = Convert.ToChar(prefixValue).ToString();
    // Create a random number, pad with zeroes
    string suffix = random.Next(1, 1000).ToString("000");
    // Combine the prefix and suffix together, then assign to current OrderID
    orderIDs[i] = prefix + suffix;
}
// Print out each orderID
foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

    הערה

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

  10. קח דקה כדי לראות אם אתה יכול להבין את מטרת הקוד.

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

  11. שקול כיצד תוכל לשפר את ההערות.

    שים לב שיש שתי בעיות עיקריות בהערות אלה:

    • הערות הקוד מסבירות שלא לצורך את הפונקציונליות הברורה של שורות קוד בודדות. הערות אלה נחשבות להערות באיכות נמוכה מכיוון שהן רק מסבירות כיצד C# או שיטות של ספריית הכיתה של .NET פועלות. אם הקורא אינו מוכר לרעיונות אלה, הוא יכול לחפש אותם באמצעות learn.microsoft.com או IntelliSense.
    • הערות הקוד אינן מספקות הקשר לבעיה שפתרת על-ידי הקוד. אלה נחשבות להערות באיכות נמוכה מכיוון שהקורא אינו משיג תובנות לגבי מטרת הקוד, במיוחד כאשר הוא מתייחס למערכת הגדולה יותר.

  12. הסר את ההערות הקיימות.

    הקוד שלך אמור להתאים לפריטים הבאים:

    Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

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

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

    /*
  The following code creates five random OrderIDs
  to test the fraud detection process.  OrderIDs 
  consist of a letter from A to E, and a three
  digit number. Ex. A123.
*/
Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

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

תקציר

הפעולות העיקריות בתרגיל זה:

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