同學們認為註釋很簡單，那我來看看下面的程式碼是否正確？

1.似是而非的問題

 1 int main()
 2 {
 3     int/*...*/i;  
 4     char* s = "abcdefgh      //hijklmn"; 
 5     //Is it a \            //
 6     valid comment?    
 7     in/*...*/t i;   
 8     return 0;
 9     
10 }

你的答案是什麼呢?

答案：

　　只有第七行出錯。

2.註釋規則

　　編譯器在編譯過程中使用空格替換整個註釋

　　字串字串字面量中的 // 和 /*...*/不代表註釋符號

　　/*......*/型註釋不能被巢狀（在分段排除異常往往被忽略）

 3.有趣的問題

你覺得y=x/*p是什麼意思？

作者本意：

　　把x除以*p的結果賦值給y。

編譯器：

　　將/*作為一段註釋的開始，把/* 後面的內容都當成註釋內容，直到*/出現為止。

　　在編譯器看來，註釋和其它程式元素是平等的，因此，作為工程師不能輕視註釋,可以用x/ *p表示（空格的重要性）

（1）、教科書式註釋：

1     r = n / 2; //r是n的一半
2     while( ( r - n / r ) <= t) //迴圈，僅當r-n/r不大於t
3     {
4         
5
 
     } 
6     r=r+n*t; //對變數r進行賦值
7     
8     n++; //變數n自增1

註釋用於闡述原因和意圖而不是描述程式的執行過程！上面的註釋一點用都沒有！！！！

（2）、迷惑型註釋：

1     init();
2     
3     //......
4     
5     sad = 0x723; //R.I.P.L.V.B.
6     
7     //......
8   
9     finalize();

解釋：Rest in piece , Ludwig Van Benthoven， 0x723(16)=1827(10) 原作者看到這行程式碼，懷戀貝多芬！！

寫註釋不是晒心情，必須無二義性，起到對程式碼進行提示的作用，避免使用縮寫

（3）、忽悠型註釋：

 1     // ... ...
 2     // ... ...
 3     
 4     // BOB 07/24/1995
 5     /* 我知道這個問題很難解決而且
 6     * 現在必須依賴於這個 contains 函式，
 7     * 但我以後會用一種更加直觀優雅有意義的方式
 8     * 重寫著段程式碼。
 9     * 現在這麼做只是由於時間緊迫，但我一定會解決。
10     */
11     
12     if( contains(s, "error" ) ) 
13     {
14         exit(1);
15     }
16     // ... ...
17     
18     // ... ...

然而一直沒改

註釋是對程式碼的提示，避免臃腫和喧兵奪主

（4）、搞笑型註釋：

 1 /** 
 2  *                             _ooOoo_ 
 3  *                            o8888888o 
 4  *                            88" . "88 
 5  *                            (| -_- |) 
 6  *                            O\  =  /O 
 7  *                         ____/`---'\____ 
 8  *                       .'  \\|     |//  `. 
 9  *                      /  \\|||  :  |||//  \ 
10  *                     /  _||||| -:- |||||-  \ 
11  *                     |   | \\\  -  /// |   | 
12  *                     | \_|  ''\---/''  |   | 
13  *                     \  .-\__  `-`  ___/-. / 
14  *                   ___`. .'  /--.--\  `. . __ 
15  *                ."" '<  `.___\_<|>_/___.'  >'"". 
16  *               | | :  `- \`.;`\ _ /`;.`/ - ` : | | 
17  *               \  \ `-.   \_ __\ /__ _/   .-` /  / 
18  *          ======`-.____`-.___\_____/___.-`____.-'====== 
19  *                             `=---=' 
20  *          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
21  *                     佛祖保佑        永無BUG 
22  *            佛曰: 
23  *                   寫字樓裡寫字間，寫字間里程序員； 
24  *                   程式人員寫程式，又拿程式換酒錢。 
25  *                   酒醒只在網上坐，酒醉還來網下眠； 
26  *                   酒醉酒醒日復日，網上網下年復年。 
27  *                   但願老死電腦間，不願鞠躬老闆前； 
28  *                   賓士寶馬貴者趣，公交自行程式設計師。 
29  *                   別人笑我忒瘋癲，我笑自己命太賤； 
30  *                   不見滿街漂亮妹，哪個歸得程式設計師？ 
31 */  

4.小結

註釋應該精準易懂，防止二義性，錯誤的註釋有害無利

               註釋是對程式碼的提示，避免臃腫和喧兵奪主

               一目瞭然的程式碼避免加註釋

               不要用縮寫來註釋程式碼，這樣可能產生誤解

               註釋用來闡述原因和意圖而不是描述程式的執行機制
5.漂亮的註釋

   1 /* 
   2   ======================================================================== 
   3  
   4   FILE:  Form.c 
   5    
   6   SERVICES:   
   7  
   8   GENERAL DESCRIPTION: Concrete implementation of RootForm and base IForm 
   9   methods 
  10  
  11   ======================================================================== 
  12   ======================================================================== 
  13      
  14                Copyright ?1999-2005 QUALCOMM Incorporated  
  15                      All Rights Reserved. 
  16                    QUALCOMM Proprietary/GTDR 
  17      
  18   ======================================================================== 
  19   ======================================================================== 
  20 */  
  21   
  22   
  23 /*================================================================================== 
  24                          XXXXXXX Confidential Proprietary 
  25                    (c) Copyright XXXXXXX - All Rights Reserved 
  26  
  27 Revision History: 
  28                          Modification 
  29   Author                     Date        CR Number      Major Changes 
  30 ----------------------   ------------   ------------   ---------------------------- 
  31 Daniel Rossler            01/18/2007     LIBkk94550    Add check for NULL pointers 
  32                                                        in order to avoid a panic 
  33 ==================================================================================*/  
  34   
  35   
  36   
  37 #include "FormBase.h"  
  38   
  39 #include "AEESoftkeyWidget.h"  
  40 #include "AEEImageWidget.h"  
  41 #include "AEEStaticWidget.h"  
  42 #include "AEEImageStaticWidget.h"  
  43 #include "AEERootContainer.h"  
  44 #include "AEEWProperties.h"  
  45 #include "AEEVectorModel.h"  
  46   
  47 #include "AEEWeb.h"  
  48   
  49 #include "AEERootForm.h"  
  50 #include "AEEResFile.h"  
  51   
  52 #include "FormUtil.h"  
  53 #include "AEEDisplayCanvas.h"  
  54   
  55 #define FORMSTACK_MIN  10  
  56 #define FORMSTACK_GROW 2  
  57   
  58 /////////////////////////////////////////////////////////////////  
  59 // RootForm  
  60   
  61 typedef struct RootForm {  
  62    Form              base;  
  63   
  64    IRootContainer *  piContainer;  
  65    AEERect           rcContainer;  
  66    AEERect           rcClient;  
  67   
  68    IVectorModel *    piForms;  
  69    ModelListener     mlFormActive;  
  70    ModelListener     mlFormTopmostNonPopup;  
  71   
  72    IWidget *         piTitle;  
  73    ImageStaticInfo   titleInfo;  
  74    IWidget *         piSoftkeys;  
  75    IWidget *         piBackground;  
  76   
  77    IWidget *         piActiveWidget;    
  78   
  79    IResFile *        piThemeFile;  
  80    const char *      themeFile;  
  81 } RootForm;  
  82   
  83 #define DECL(c) c* me = (c *)po  
  84   
  85 static __inline IForm *ROOTFORM_TO_IFORM(RootForm *me) {  
  86    return (IForm *)me;  
  87 }  
  88   
  89 static __inline Form *ROOTFORM_TO_FORM(RootForm *me) {  
  90    return (Form *)me;  
  91 }  
  92   
  93 static __inline IRootForm *ROOTFORM_TO_IROOTFORM(RootForm *me) {  
  94    return (IRootForm *)me;  
  95 }  
  96   
  97 static void RootForm_FreeFormEntry(IForm *po)  
  98 {  
  99    IFORM_Release(po);  
 100 }  
 101   
 102 static void RootForm_UpdateClientArea(RootForm *me)  
 103 {  
 104    WidgetPos pos;  
 105    WExtent titleExtent, skExtent;  
 106   
 107    if (me->piSoftkeys) {  
 108       IWIDGET_GetExtent(me->piSoftkeys, &skExtent);  
 109    
 110       // Adjust softkey position based on current height  
 111       IROOTCONTAINER_GetPos(me->piContainer, me->piSoftkeys, &pos);  
 112       pos.y = me->rcContainer.dy - skExtent.height;  
 113       IROOTCONTAINER_SetPos(me->piContainer, me->piSoftkeys, WIDGET_ZNORMAL, &pos);  
 114    } else {  
 115       SETWEXTENT(&skExtent, 0, 0);  
 116    }  
 117   
 118    if (me->piTitle) {  
 119       IWIDGET_GetExtent(me->piTitle, &titleExtent);  
 120    } else {  
 121       SETWEXTENT(&titleExtent, 0, 0);  
 122    }  
 123      
 124    // Calculate client area  
 125    SETAEERECT(&me->rcClient, 0, titleExtent.height,  
 126               me->rcContainer.dx,  
 127               me->rcContainer.dy - skExtent.height - titleExtent.height);  
 128 }  
 129   
 130   
 131 static void RootForm_UpdateTheme(RootForm *me, const char *baseName)  
 132 {  
 133    WExtent wextent;  
 134   
 135    BUIT_LOG("FORMS EVT: Update Theme Started for %s", baseName);  
 136   
 137    if (!me->piThemeFile)  
 138       return;  
 139   
 140    if (me->piTitle) {  
 141       IWIDGET_SetProperties(me->piTitle, me->piThemeFile, baseName, "Title", "Properties", 0);  
 142       IWIDGET_GetPreferredExtent(me->piTitle, &wextent);  
 143       wextent.width = me->rcContainer.dx;  
 144       IWIDGET_SetExtent(me->piTitle, &wextent);  
 145    }  
 146   
 147    if (me->piSoftkeys) {  
 148       IWIDGET_SetProperties(me->piSoftkeys, me->piThemeFile, baseName, "Softkeys", "Properties", 0);  
 149       IWIDGET_GetPreferredExtent(me->piSoftkeys, &wextent);  
 150       wextent.width = me->rcContainer.dx;  
 151       IWIDGET_SetExtent(me->piSoftkeys, &wextent);  
 152    }  
 153   
 154    if (me->piBackground) {  
 155       IWIDGET_SetProperties(me->piBackground, me->piThemeFile, baseName, "Background", "Properties", 0);  
 156    }  
 157   
 158    // Update client area since sizes may have changed  
 159    RootForm_UpdateClientArea(me);  
 160   
 161    BUIT_LOG("FORMS EVT: Update Theme Finished for %s", baseName);  
 162 }  
 163   
 164 // updates the rootform with the background image, softkey and   
 165 // title text of the TOS form.  
 166 static void RootForm_Update(RootForm *me, uint32 dwItemMask, IForm* piForm)  
 167 {  
 168    boolean bPopup = 0;  
 169   
 170    // get form's popup flag  
 171    bPopup = IFORM_GetIsPopup(piForm);  
 172   
 173    // if the form's widget has changed, update the scroll model  
 174    // for the scroll indicator in the softkey widget  
 175    if (dwItemMask & FORMITEM_WIDGET) {  
 176         
 177       IWidget *piWidget = NULL;  
 178       // get form's widget  
 179       IFORM_GetWidget(piForm, WID_FORM, &piWidget);  
 180   
 181       // update the widget and the scroll model  
 182       if (piWidget) {  
 183   
 184          // if the active widget has been changed underneath us...  
 185            
 186          if (me->piActiveWidget && piWidget != me->piActiveWidget) {  
 187             // this block will only be executed when the form widget is changed  
 188             // by the application logic while the form is active  
 189             WidgetPos pos;  
 190             WExtent we;  
 191      
 192             IWIDGET_MoveFocus(FORM_WIDGET(me), (IWidget*)WIDGET_FOCUS_NONE);  
 193      
 194             IWIDGET_GetExtent(me->piActiveWidget, &we);  
 195             IWIDGET_SetExtent(piWidget, &we);  
 196      
 197             // remove the previously active widget from the root container  
 198             if (AEE_SUCCESS == IROOTCONTAINER_GetPos(me->piContainer, me->piActiveWidget, &pos)) {  
 199                IROOTCONTAINER_Remove(me->piContainer, me->piActiveWidget);  
 200             }  
 201               
 202             // add the new widget to the root container  
 203             IROOTCONTAINER_Insert(me->piContainer, piWidget, WIDGET_ZTOPMOST, &pos);  
 204             // and remember it fondly  
 205             RELEASEIF(me->piActiveWidget);  
 206             me->piActiveWidget = piWidget;  
 207             ADDREFIF(piWidget);  
 208   
 209             // set focus to the new widget  
 210             IWIDGET_MoveFocus(FORM_WIDGET(me), piWidget);  
 211            
 212          } else if (!me->piActiveWidget) {  
 213             me->piActiveWidget = piWidget;  
 214             ADDREFIF(piWidget);  
 215          }  
 216   
 217       }  
 218   
 219       RELEASEIF(piWidget);  
 220    }  
 221   
 222   
 223    // if the form's background image has changed...  
 224    // if form is a popup, then retain the background image   
 225    // from the previous form  
 226    if (dwItemMask & FORMITEM_BACKGROUND && me->piBackground && !bPopup) {        
 227       IImage *pii = NULL;  
 228         
 229       // Try to grab the image from the new form.    
 230       IFORM_GetBGImage(piForm, &pii);  
 231   
 232       // If non-existent, try defaulting to the root form  
 233       if (!pii) IFORM_GetBGImage(ROOTFORM_TO_IFORM(me), &pii);  
 234         
 235       // Apply the result (NULL or otherwise) to our background widget  
 236       IWIDGET_SetImage(me->piBackground, pii);  
 237       RELEASEIF(pii);  
 238    }  
 239      
 240    // if the form's title text has changed...  retain previous title  
 241    // if we are a popup   
 242   
 243    if ((dwItemMask & FORMITEM_TITLE) && me->piTitle && !bPopup) {  
 244       // Release image. Text is owned by form  
 245       RELEASEIF(me->titleInfo.piImage);  
 246       IFORM_GetTextPtr(piForm, FID_TITLE, &me->titleInfo.pwText);  
 247       IFORM_GetTitleImage(piForm, &me->titleInfo.piImage);  
 248   
 249       // Set title info  
 250       IWIDGET_SetImageStaticInfo(me->piTitle, &me->titleInfo, 0);  
 251    }  
 252   
 253    // if the form's softkey text has changed...  
 254    if ((dwItemMask & FORMITEM_SOFTKEY) && me->piSoftkeys) {  
 255   
 256       IForm* piTopForm = IROOTFORM_GetTopForm(ROOTFORM_TO_IROOTFORM(me));  
 257   
 258       AECHAR *pwsz = NULL;  
 259       IWidget *piKey = NULL;  
 260   
 261       if (piTopForm == piForm) {  
 262          // set softkey 1 text  
 263          IFORM_GetTextPtr(piForm, FID_SOFTKEY1, &pwsz);  
 264          if (AEE_SUCCESS == IWIDGET_GetSoftkey(me->piSoftkeys, PROP_SOFTKEY1, &piKey)) {  
 265             IWIDGET_SetText(piKey, pwsz, 0);  
 266          }  
 267          RELEASEIF(piKey);  
 268      
 269          // set softkey 2 text  
 270          IFORM_GetTextPtr(piForm, FID_SOFTKEY2, &pwsz);  
 271          if (AEE_SUCCESS == IWIDGET_GetSoftkey(me->piSoftkeys, PROP_SOFTKEY2, &piKey)) {  
 272             IWIDGET_SetText(piKey, pwsz, 0);  
 273          }  
 274       }  
 275       RELEASEIF(piKey);  
 276    }  
 277   
 278    if ((dwItemMask & FORMITEM_THEME_BASENAME)) {  
 279       char *baseName = 0;  
 280   
 281       IFORM_GetThemeBaseName(piForm, &baseName);  
 282       RootForm_UpdateTheme(me, baseName);  
 283    }  
 284   
 285 }  
 286   
 287 static boolean RootForm_ReplaceWidget(RootForm *me, IWidget **piw, IWidget *piwNew, IWidget *piwBefore)  
 288 {  
 289    int        result = AEE_SUCCESS;  
 290    WidgetPos  pos;  
 291   
 292    if (*piw) {  
 293       (void) IROOTCONTAINER_GetPos(me->piContainer, *piw, &pos);  
 294       (void) IROOTCONTAINER_Remove(me->piContainer, *piw);  
 295       IWIDGET_Release(*piw);  
 296    }  
 297   
 298    if (piwNew) {  
 299       result = IROOTCONTAINER_Insert(me->piContainer, piwNew, piwBefore, &pos);  
 300         
 301       if (result == AEE_SUCCESS) {  
 302          IWIDGET_AddRef(piwNew);  
 303       } else {  
 304          piwNew = NULL;  
 305       }  
 306    }  
 307   
 308    *piw = piwNew;  
 309   
 310    // Do an update since extents may have changed  
 311    RootForm_UpdateClientArea(me);  
 312   
 313    return (AEE_SUCCESS == result);  
 314 }  
 315   
 316 static int RootForm_SetThemeName(RootForm *me, const char *themeFile)  
 317 {  
 318    if (!me->piThemeFile)  
 319       return EBADSTATE;  
 320      
 321    FREEIF(me->themeFile);  
 322    me->themeFile = STRDUP(themeFile);  
 323      
 324    IRESFILE_Close(me->piThemeFile);  
 325    if (themeFile)  
 326       return IRESFILE_Open(me->piThemeFile, themeFile);  
 327    else  
 328       return AEE_SUCCESS;  
 329 }  
 330   
 331 static int RootForm_SetDisplay(RootForm *me, IDisplay *piDisplay)  
 332 {  
 333    int nErr = AEE_SUCCESS;  
 334    IDisplayCanvas *piCanvas = 0;  
 335   
 336    nErr = ISHELL_CreateInstance(FORM_SHELL(me), AEECLSID_DISPLAYCANVAS, (void **)&piCanvas);  
 337         
 338    if (!nErr) {  
 339       WExtent extent;  
 340       WidgetPos pos;  
 341         
 342   
 343       IDISPLAY_SetClipRect(piDisplay, NULL); // reset the clipping rectangle  
 344       IDISPLAY_GetClipRect(piDisplay, &me->rcContainer);  
 345       SETAEERECT(&me->rcClient, 0, 0, me->rcContainer.dx, me->rcContainer.dy);  
 346   
 347       IDISPLAYCANVAS_SetDisplay(piCanvas, piDisplay);  
 348       IROOTCONTAINER_SetCanvas(me->piContainer, (ICanvas *)piCanvas, &me->rcContainer);  
 349   
 350       if (me->piTitle) {  
 351          // Set extent, title is already positioned at 0, 0  
 352          IWIDGET_GetExtent(me->piTitle, &extent);  
 353          extent.width = me->rcContainer.dx;  
 354          IWIDGET_SetExtent(me->piTitle, &extent);  
 355       }  
 356   
 357       if (me->piBackground) {  
 358          // Set extent, background is already positioned at 0, 0  
 359          extent.width = me->rcContainer.dx;  
 360          extent.height = me->rcContainer.dy;  
 361          IWIDGET_SetExtent(me->piBackground, &extent);  
 362       }  
 363   
 364       if (me->piSoftkeys) {  
 365          // Set extent  
 366          IWIDGET_GetExtent(me->piSoftkeys, &extent);  
 367          extent.width = me->rcContainer.dx;  
 368          IWIDGET_SetExtent(me->piSoftkeys, &extent);  
 369          // And position at bottom of screen  
 370          IROOTCONTAINER_GetPos(me->piContainer, me->piSoftkeys, &pos);  
 371          pos.y = me->rcContainer.dy - extent.height;  
 372          IROOTCONTAINER_SetPos(me->piContainer, WIDGET_ZNORMAL, me->piSoftkeys, &pos);  
 373       }  
 374    }  
 375   
 376    RELEASEIF(piCanvas);  
 377   
 378    return nErr;  
 379 }  
 380   
 381   
 382 static void RootForm_ApplyTheme(RootForm *me)  
 383 {  
 384    int nrForms, i;  
 385   
 386    if (!me->piThemeFile)   
 387       return;  
 388      
 389    nrForms = IVECTORMODEL_Size(me->piForms);  
 390    for (i = 0; i < nrForms; i++) {  
 391       IForm *piForm;  
 392       char* pTheme = 0;  
 393       IVECTORMODEL_GetAt(me->piForms, i, (void **)&piForm);  
 394         
 395       IFORM_GetThemeBaseName(ROOTFORM_TO_IFORM(me), &pTheme);  
 396       pTheme = (pTheme) ? pTheme : "(None)";  
 397         
 398       BUIT_LOG("FORMS EVT: Apply Theme Started for %s", pTheme);  
 399         
 400       IFORM_ApplyTheme(piForm);  
 401         
 402       BUIT_LOG("FORMS EVT: Apply Theme Finished for %s", pTheme);  
 403    }  
 404   
 405    if (nrForms == 0) {  
 406       char *baseName = 0;  
 407         
 408       IFORM_GetThemeBaseName(ROOTFORM_TO_IFORM(me), &baseName);  
 409 #ifdef FEATURE_MOT_BREW  
 410       if (baseName != NULL) {  
 411           RootForm_UpdateTheme(me, baseName);  
 412       }  
 413 #else  
 414       RootForm_UpdateTheme(me, baseName);  
 415 #endif /*FEATURE_MOT_BREW*/  
 416    }  
 417 }  
 418   
 419 boolean RootForm_HandleEvent(IRootForm *po, AEEEvent evt, uint16 wParam, uint32 dwParam)  
 420 {  
 421    DECL(RootForm);  
 422   
 423    if (FORM_WIDGET(me)  
 424       && IWIDGET_HandleEvent(FORM_WIDGET(me), evt, wParam, dwParam))  
 425       return TRUE;  
 426   
 427    if (evt == EVT_WDG_GETPROPERTY) {  
 428       switch(wParam) {  
 429       case FID_THEME_FNAME:  
 430          *(const char **)dwParam = me->themeFile;  
 431          return TRUE;  
 432   
 433       case FID_THEME_FILE:  
 434          *(IResFile **)dwParam = me->piThemeFile;  
 435          ADDREFIF(me->piThemeFile);  
 436          return TRUE;  
 437   
 438       case WID_TITLE:  
 439          *(IWidget **)dwParam = me->piTitle;  
 440          ADDREFIF(me->piTitle);  
 441          return TRUE;  
 442   
 443       case WID_SOFTKEYS:  
 444          *(IWidget **)dwParam = me->piSoftkeys;  
 445          ADDREFIF(me->piSoftkeys);  
 446          return TRUE;  
 447   
 448       case WID_BACKGROUND:  
 449          *(IWidget **)dwParam = me->piBackground;  
 450          ADDREFIF(me->piBackground);  
 451          return TRUE;  
 452   
 453       case WID_FORM:  
 454          IROOTCONTAINER_QueryInterface(me->piContainer, AEEIID_WIDGET, (void **)dwParam);  
 455          return TRUE;  
 456   
 457       case WID_CONTAINER:  
 458          *(IContainer **)dwParam = IROOTCONTAINER_TO_ICONTAINER(me->piContainer);  
 459          ADDREFIF(me->piContainer);  
 460          return TRUE;  
 461   
 462       default:  
 463          // Fall back on formbase  
 464          return Form_HandleEvent(ROOTFORM_TO_IFORM(me), evt, wParam, dwParam);  
 465       }  
 466   
 467    } else if (evt == EVT_WDG_SETPROPERTY) {  
 468       IForm *piForm = 0;  
 469   
 470       switch(wParam) {  
 471       case FID_ACTIVE:  
 472          piForm = IROOTFORM_GetTopForm(po);  
 473          if (piForm) {  
 474             // Activate or de-activate the top form  
 475