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

קוים מנחים

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

מבנה

דוגמא

//---------------------------------------------------------------
//                              CarDistanceMeter
//
//  General: This function calculates the remaining distance a car
//           can ride without refueling 
//
//  Input:  Fuel left in tank,
//          the car's fuel consumption.
//
//  Process: ....
//
//  Output: Distance in km
//---------------------------------------------------------------
// programmer: Duvid Schweizer
// Date: July, 1974

•

הערה ראשית כדוגמת זו תבוא בראש כל תוכנית שנכתוב.

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

לדוגמא: אם אין סעיף קלט, אז אין קלט, או ששכחו אותו?

פתרון: הסעיף תמיד יופיע, ובמקום התאור שלו נרשום None.

 

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