C语言进阶——注释符号12

注释可能大认为非常简单，但是注释其实在C语言中很关键，来看下面一段对话。

---学生：

　　老师，我觉得注释没有必要深究，因为很简单，对程序功能也没有影响。

---老师：

　　注释是C语言最重要的工具，我们先看自己有没有能力驾驭它，再讨论有没有必要深究。

请判断下面的程序示例是否正确：

 #include<stdio.h>

 int main()
 {
     int/*...*/i;
     char *s="dkfjslj //dkhsf";
     //is it a\
     valid comment?
     in/*...*/t j;
     return ;
 }

这段代码运行一下，其实只有第九行会报错。为什么呢？请看下面的规则：

• 编译器在编译的过程中，使用空格替换整个注释
• 字符串字面值中的//和/*...*/ 不代表注释符号
• /*...*/型注释不能被嵌套
• \  换行符代表这一行没有结束，所以代码示例的第八行和第七行其实是一行，因为添加了//行注释，所以第八行不符合C语言语法规范的语句没有报错

你觉得 y=x/*p是什么意思？

作者本意：把x除以*p的结果赋值给y

编译器：把/* 作为一段注释的开始，把/* 后的内容都当做成注释内容，知道出现*/为止。

在编译器看来，注释和其他程序元素是平等的，作为工程师不能轻视注释。

以上的代码我们可以在/ 和 *中间加上一个空格就可以解决这个问题   y=x / *p

常见的几种注释的错误：

1.教科书式的注释

int main()
{
    r = n / ;   //r 是n的一半
    while((r - n / r)<= t)  //循环，仅当 r - n / r 不大于t
    {

    }
    r = r + n * t;   //对变量 r 进行赋值
    n++;   //变量n自增1

    return ;
}

我就想问这样的代码我们是看不懂还是咋的，为什么要画蛇添足？

2.晒心情的注释

 int main()
 {
     init();
     //......
     //......
     sad = 0x723;   //R,I,P,L,V,B.
     //......
     //.....
     finalize();
     return ;
 }

第六行的注释是缩写  真正完整的是   Rest in peace ,Ludwig Van Benthoven.   安息吧，贝多芬。   0x723的十进制是1827 伟大的贝多芬去世的那一年，卧槽，这不就是在晒心情吗？

3.忽悠性注释

int main()
{
    //.....
    //.....
    //Bob 07/24/1995
    /*我知道这个问题很难解决而且
    我现在必须依赖这个contains函数
    但是我以后会用一种更好的方法去解决他
    重写这段代码
    现在这么做事由于时间紧迫，但是我一定会解决。
    */
    if (contains(s,"error"))
    {
        exit()
    }
    //......
    //......
    return ;
}

注释是对代码的解释，避免臃肿和喧宾夺主。

4.搞笑型注释

有的人在注释中画一个佛祖，来保佑代码不会出现bug

佛祖是佛学的专业大师，但是没有学过编程，因此保佑不了你，只能靠你自己去避开bug。

给一段高通公司的漂亮的注释代码：

 /*
   ========================================================================

   FILE:  Form.c

   SERVICES:  

   GENERAL DESCRIPTION: Concrete implementation of RootForm and base IForm
   methods

   ========================================================================
   ========================================================================

                Copyright ?1999-2005 QUALCOMM Incorporated
                      All Rights Reserved.
                    QUALCOMM Proprietary/GTDR

   ========================================================================
   ========================================================================
 */

 /*==================================================================================
                          XXXXXXX Confidential Proprietary
                    (c) Copyright XXXXXXX - All Rights Reserved

 Revision History:
                          Modification
   Author                     Date        CR Number      Major Changes
 ----------------------   ------------   ------------   ----------------------------
 Daniel Rossler            01/18/2007     LIBkk94550    Add check for NULL pointers
                                                        in order to avoid a panic
 ==================================================================================*/

 #include "FormBase.h"

 #include "AEESoftkeyWidget.h"
 #include "AEEImageWidget.h"
 #include "AEEStaticWidget.h"
 #include "AEEImageStaticWidget.h"
 #include "AEERootContainer.h"
 #include "AEEWProperties.h"
 #include "AEEVectorModel.h"

 #include "AEEWeb.h"

 #include "AEERootForm.h"
 #include "AEEResFile.h"

 #include "FormUtil.h"
 #include "AEEDisplayCanvas.h"

 #define FORMSTACK_MIN  10
 #define FORMSTACK_GROW 2

 /////////////////////////////////////////////////////////////////
 // RootForm

 typedef struct RootForm {
    Form              base;

    IRootContainer *  piContainer;
    AEERect           rcContainer;
    AEERect           rcClient;

    IVectorModel *    piForms;
    ModelListener     mlFormActive;
    ModelListener     mlFormTopmostNonPopup;

    IWidget *         piTitle;
    ImageStaticInfo   titleInfo;
    IWidget *         piSoftkeys;
    IWidget *         piBackground;

    IWidget *         piActiveWidget;  

    IResFile *        piThemeFile;
    const char *      themeFile;
 } RootForm;

 #define DECL(c) c* me = (c *)po

 static __inline IForm *ROOTFORM_TO_IFORM(RootForm *me) {
    return (IForm *)me;
 }

 static __inline Form *ROOTFORM_TO_FORM(RootForm *me) {
    return (Form *)me;
 }

 static __inline IRootForm *ROOTFORM_TO_IROOTFORM(RootForm *me) {
    return (IRootForm *)me;
 }

 static void RootForm_FreeFormEntry(IForm *po)
 {
    IFORM_Release(po);
 }

 static void RootForm_UpdateClientArea(RootForm *me)
 {
    WidgetPos pos;
    WExtent titleExtent, skExtent;

    if (me->piSoftkeys) {
       IWIDGET_GetExtent(me->piSoftkeys, &skExtent);

       // Adjust softkey position based on current height
       IROOTCONTAINER_GetPos(me->piContainer, me->piSoftkeys, &pos);
       pos.y = me->rcContainer.dy - skExtent.height;
       IROOTCONTAINER_SetPos(me->piContainer, me->piSoftkeys, WIDGET_ZNORMAL, &pos);
    } else {
       SETWEXTENT(&skExtent, , );
    }

    if (me->piTitle) {
       IWIDGET_GetExtent(me->piTitle, &titleExtent);
    } else {
       SETWEXTENT(&titleExtent, , );
    }

    // Calculate client area
    SETAEERECT(&me->rcClient, , titleExtent.height,
               me->rcContainer.dx,
               me->rcContainer.dy - skExtent.height - titleExtent.height);
 }

 static void RootForm_UpdateTheme(RootForm *me, const char *baseName)
 {
    WExtent wextent;

    BUIT_LOG("FORMS EVT: Update Theme Started for %s", baseName);

    if (!me->piThemeFile)
       return;

    if (me->piTitle) {
       IWIDGET_SetProperties(me->piTitle, me->piThemeFile, baseName, "Title", "Properties", );
       IWIDGET_GetPreferredExtent(me->piTitle, &wextent);
       wextent.width = me->rcContainer.dx;
       IWIDGET_SetExtent(me->piTitle, &wextent);
    }

    if (me->piSoftkeys) {
       IWIDGET_SetProperties(me->piSoftkeys, me->piThemeFile, baseName, "Softkeys", "Properties", );
       IWIDGET_GetPreferredExtent(me->piSoftkeys, &wextent);
       wextent.width = me->rcContainer.dx;
       IWIDGET_SetExtent(me->piSoftkeys, &wextent);
    }

    if (me->piBackground) {
       IWIDGET_SetProperties(me->piBackground, me->piThemeFile, baseName, "Background", "Properties", );
    }

    // Update client area since sizes may have changed
    RootForm_UpdateClientArea(me);

    BUIT_LOG("FORMS EVT: Update Theme Finished for %s", baseName);
 }

 // updates the rootform with the background image, softkey and
 // title text of the TOS form.
 static void RootForm_Update(RootForm *me, uint32 dwItemMask, IForm* piForm)
 {
    boolean bPopup = ;

    // get form's popup flag
    bPopup = IFORM_GetIsPopup(piForm);

    // if the form's widget has changed, update the scroll model
    // for the scroll indicator in the softkey widget
    if (dwItemMask & FORMITEM_WIDGET) {

       IWidget *piWidget = NULL;
       // get form's widget
       IFORM_GetWidget(piForm, WID_FORM, &piWidget);

       // update the widget and the scroll model
       if (piWidget) {

          // if the active widget has been changed underneath us...

          if (me->piActiveWidget && piWidget != me->piActiveWidget) {
             // this block will only be executed when the form widget is changed
             // by the application logic while the form is active
             WidgetPos pos;
             WExtent we;

             IWIDGET_MoveFocus(FORM_WIDGET(me), (IWidget*)WIDGET_FOCUS_NONE);

             IWIDGET_GetExtent(me->piActiveWidget, &we);
             IWIDGET_SetExtent(piWidget, &we);

             // remove the previously active widget from the root container
             if (AEE_SUCCESS == IROOTCONTAINER_GetPos(me->piContainer, me->piActiveWidget, &pos)) {
                IROOTCONTAINER_Remove(me->piContainer, me->piActiveWidget);
             }

             // add the new widget to the root container
             IROOTCONTAINER_Insert(me->piContainer, piWidget, WIDGET_ZTOPMOST, &pos);
             // and remember it fondly
             RELEASEIF(me->piActiveWidget);
             me->piActiveWidget = piWidget;
             ADDREFIF(piWidget);

             // set focus to the new widget
             IWIDGET_MoveFocus(FORM_WIDGET(me), piWidget);

          } else if (!me->piActiveWidget) {
             me->piActiveWidget = piWidget;
             ADDREFIF(piWidget);
          }

       }

       RELEASEIF(piWidget);
    }

    // if the form's background image has changed...
    // if form is a popup, then retain the background image
    // from the previous form
    if (dwItemMask & FORMITEM_BACKGROUND && me->piBackground && !bPopup) {
       IImage *pii = NULL;

       // Try to grab the image from the new form.
       IFORM_GetBGImage(piForm, &pii);

       // If non-existent, try defaulting to the root form
       if (!pii) IFORM_GetBGImage(ROOTFORM_TO_IFORM(me), &pii);

       // Apply the result (NULL or otherwise) to our background widget
       IWIDGET_SetImage(me->piBackground, pii);
       RELEASEIF(pii);
    }

    // if the form's title text has changed...  retain previous title
    // if we are a popup 

    if ((dwItemMask & FORMITEM_TITLE) && me->piTitle && !bPopup) {
       // Release image. Text is owned by form
       RELEASEIF(me->titleInfo.piImage);
       IFORM_GetTextPtr(piForm, FID_TITLE, &me->titleInfo.pwText);
       IFORM_GetTitleImage(piForm, &me->titleInfo.piImage);

       // Set title info
       IWIDGET_SetImageStaticInfo(me->piTitle, &me->titleInfo, );
    }

    // if the form's softkey text has changed...
    if ((dwItemMask & FORMITEM_SOFTKEY) && me->piSoftkeys) {

       IForm* piTopForm = IROOTFORM_GetTopForm(ROOTFORM_TO_IROOTFORM(me));

       AECHAR *pwsz = NULL;
       IWidget *piKey = NULL;

       if (piTopForm == piForm) {
          // set softkey 1 text
          IFORM_GetTextPtr(piForm, FID_SOFTKEY1, &pwsz);
          if (AEE_SUCCESS == IWIDGET_GetSoftkey(me->piSoftkeys, PROP_SOFTKEY1, &piKey)) {
             IWIDGET_SetText(piKey, pwsz, );
          }
          RELEASEIF(piKey);

          // set softkey 2 text
          IFORM_GetTextPtr(piForm, FID_SOFTKEY2, &pwsz);
          if (AEE_SUCCESS == IWIDGET_GetSoftkey(me->piSoftkeys, PROP_SOFTKEY2, &piKey)) {
             IWIDGET_SetText(piKey, pwsz, );
          }
       }
       RELEASEIF(piKey);
    }

    if ((dwItemMask & FORMITEM_THEME_BASENAME)) {
       char *baseName = ;

       IFORM_GetThemeBaseName(piForm, &baseName);
       RootForm_UpdateTheme(me, baseName);
    }

 }

 static boolean RootForm_ReplaceWidget(RootForm *me, IWidget **piw, IWidget *piwNew, IWidget *piwBefore)
 {
    int        result = AEE_SUCCESS;
    WidgetPos  pos;

    if (*piw) {
       (void) IROOTCONTAINER_GetPos(me->piContainer, *piw, &pos);
       (void) IROOTCONTAINER_Remove(me->piContainer, *piw);
       IWIDGET_Release(*piw);
    }

    if (piwNew) {
       result = IROOTCONTAINER_Insert(me->piContainer, piwNew, piwBefore, &pos);

       if (result == AEE_SUCCESS) {
          IWIDGET_AddRef(piwNew);
       } else {
          piwNew = NULL;
       }
    }

    *piw = piwNew;

    // Do an update since extents may have changed
    RootForm_UpdateClientArea(me);

    return (AEE_SUCCESS == result);
 }

 static int RootForm_SetThemeName(RootForm *me, const char *themeFile)
 {
    if (!me->piThemeFile)
       return EBADSTATE;

    FREEIF(me->themeFile);
    me->themeFile = STRDUP(themeFile);

    IRESFILE_Close(me->piThemeFile);
    if (themeFile)
       return IRESFILE_Open(me->piThemeFile, themeFile);
    else
       return AEE_SUCCESS;
 }

 static int RootForm_SetDisplay(RootForm *me, IDisplay *piDisplay)
 {
    int nErr = AEE_SUCCESS;
    IDisplayCanvas *piCanvas = ;

    nErr = ISHELL_CreateInstance(FORM_SHELL(me), AEECLSID_DISPLAYCANVAS, (void **)&piCanvas);

    if (!nErr) {
       WExtent extent;
       WidgetPos pos;

       IDISPLAY_SetClipRect(piDisplay, NULL); // reset the clipping rectangle
       IDISPLAY_GetClipRect(piDisplay, &me->rcContainer);
       SETAEERECT(&me->rcClient, , , me->rcContainer.dx, me->rcContainer.dy);

       IDISPLAYCANVAS_SetDisplay(piCanvas, piDisplay);
       IROOTCONTAINER_SetCanvas(me->piContainer, (ICanvas *)piCanvas, &me->rcContainer);

       if (me->piTitle) {
          // Set extent, title is already positioned at 0, 0
          IWIDGET_GetExtent(me->piTitle, &extent);
          extent.width = me->rcContainer.dx;
          IWIDGET_SetExtent(me->piTitle, &extent);
       }

       if (me->piBackground) {
          // Set extent, background is already positioned at 0, 0
          extent.width = me->rcContainer.dx;
          extent.height = me->rcContainer.dy;
          IWIDGET_SetExtent(me->piBackground, &extent);
       }

       if (me->piSoftkeys) {
          // Set extent
          IWIDGET_GetExtent(me->piSoftkeys, &extent);
          extent.width = me->rcContainer.dx;
          IWIDGET_SetExtent(me->piSoftkeys, &extent);
          // And position at bottom of screen
          IROOTCONTAINER_GetPos(me->piContainer, me->piSoftkeys, &pos);
          pos.y = me->rcContainer.dy - extent.height;
          IROOTCONTAINER_SetPos(me->piContainer, WIDGET_ZNORMAL, me->piSoftkeys, &pos);
       }
    }

    RELEASEIF(piCanvas);

    return nErr;
 }

 static void RootForm_ApplyTheme(RootForm *me)
 {
    int nrForms, i;

    if (!me->piThemeFile)
       return;

    nrForms = IVECTORMODEL_Size(me->piForms);
    for (i = ; i < nrForms; i++) {
       IForm *piForm;
       char* pTheme = ;
       IVECTORMODEL_GetAt(me->piForms, i, (void **)&piForm);

       IFORM_GetThemeBaseName(ROOTFORM_TO_IFORM(me), &pTheme);
       pTheme = (pTheme) ? pTheme : "(None)";

       BUIT_LOG("FORMS EVT: Apply Theme Started for %s", pTheme);

       IFORM_ApplyTheme(piForm);

       BUIT_LOG("FORMS EVT: Apply Theme Finished for %s", pTheme);
    }

    if (nrForms == ) {
       char *baseName = ;

       IFORM_GetThemeBaseName(ROOTFORM_TO_IFORM(me), &baseName);
 #ifdef FEATURE_MOT_BREW
       if (baseName != NULL) {
           RootForm_UpdateTheme(me, baseName);
       }
 #else
       RootForm_UpdateTheme(me, baseName);
 #endif /*FEATURE_MOT_BREW*/
    }
 }

 boolean RootForm_HandleEvent(IRootForm *po, AEEEvent evt, uint16 wParam, uint32 dwParam)
 {
    DECL(RootForm);

    if (FORM_WIDGET(me)
       && IWIDGET_HandleEvent(FORM_WIDGET(me), evt, wParam, dwParam))
       return TRUE;

    if (evt == EVT_WDG_GETPROPERTY) {
       switch(wParam) {
       case FID_THEME_FNAME:
          *(const char **)dwParam = me->themeFile;
          return TRUE;

       case FID_THEME_FILE:
          *(IResFile **)dwParam = me->piThemeFile;
          ADDREFIF(me->piThemeFile);
          return TRUE;

       case WID_TITLE:
          *(IWidget **)dwParam = me->piTitle;
          ADDREFIF(me->piTitle);
          return TRUE;

       case WID_SOFTKEYS:
          *(IWidget **)dwParam = me->piSoftkeys;
          ADDREFIF(me->piSoftkeys);
          return TRUE;

       case WID_BACKGROUND:
          *(IWidget **)dwParam = me->piBackground;
          ADDREFIF(me->piBackground);
          return TRUE;

       case WID_FORM:
          IROOTCONTAINER_QueryInterface(me->piContainer, AEEIID_WIDGET, (void **)dwParam);
          return TRUE;

       case WID_CONTAINER:
          *(IContainer **)dwParam = IROOTCONTAINER_TO_ICONTAINER(me->piContainer);
          ADDREFIF(me->piContainer);
          return TRUE;

       default:
          // Fall back on formbase
          return Form_HandleEvent(ROOTFORM_TO_IFORM(me), evt, wParam, dwParam);
       }

    } else if (evt == EVT_WDG_SETPROPERTY) {
       IForm *piForm = ;

       switch(wParam) {
       case FID_ACTIVE:
          piForm = IROOTFORM_GetTopForm(po);
          if (piForm) {
             // Activate or de-activate the top form
             IFORM_SetProperty(piForm, FID_ACTIVE, dwParam);
          }
          // and invalidate root container on activation
          if ((boolean)dwParam) {
             IROOTCONTAINER_Invalidate(me->piContainer, , , );
          }
          return TRUE;

       case FID_THEME:
          RootForm_ApplyTheme(me);
          return TRUE;

       case FID_THEME_FNAME:
          if (AEE_SUCCESS == RootForm_SetThemeName(me, (const char *)dwParam)) {
             RootForm_ApplyTheme(me);
             return TRUE;
          }
          return FALSE;

       case FID_BACKGROUND:
          // If we have a background widget, set the image into it
          if (me->piBackground) {
             IWIDGET_SetFormImage(me->piBackground, FORM_SHELL(me), (FormRes *)dwParam);
          }
          // Also load the image into our internal form, which will hold it as a default for other forms
          return Form_HandleEvent(ROOTFORM_TO_IFORM(me), evt, wParam, dwParam);

       case FID_DISPLAY:
          return AEE_SUCCESS == RootForm_SetDisplay(me, (IDisplay *)dwParam);

       case FID_WPROPS: {
          WPropDesc *pdesc = (WPropDesc *)dwParam;
          WResPropDesc wd;

          wd.piResFile = me->piThemeFile;
          if (pdesc) {
             wd.args = pdesc->args;
             wd.piWidget = pdesc->piWidget;
          }
          return IWIDGET_SetProperty(pdesc->piWidget, PROP_APPLYWPROPS, (uint32)&wd);
       }

       case WID_TITLE:
          return RootForm_ReplaceWidget(me, &me->piTitle, (IWidget *)dwParam, WIDGET_ZNORMAL);

       case WID_SOFTKEYS:
          return RootForm_ReplaceWidget(me, &me->piSoftkeys, (IWidget *)dwParam, WIDGET_ZNORMAL);

       case WID_BACKGROUND:
          return RootForm_ReplaceWidget(me, &me->piBackground, (IWidget *)dwParam, WIDGET_ZBOTTOMMOST);

       default:
          // Fall back on formbase
          return Form_HandleEvent(ROOTFORM_TO_IFORM(me), evt, wParam, dwParam);
       }
    }

    // Non get/set property events are sent on to the topmost form
    {
       IForm *piForm = IROOTFORM_GetTopForm(po);
       if (!piForm)
          return FALSE;
       else
          return IFORM_HandleEvent(piForm, evt, wParam, dwParam);
    }
 }

 static void RootForm_UpdateActiveListenerCB(RootForm *me, FormEvent *pEvent)
 {
    if (pEvent->base.evCode == EVT_MDL_FORM_CHANGE) {
       RootForm_Update(me, pEvent->dwItemMask, pEvent->piForm);
    }
 }

 static void RootForm_UpdateTopmostNonPopupListenerCB(RootForm *me, FormEvent *pEvent)
 {
    uint32 dwItemMask = pEvent->dwItemMask & (FORMITEM_BACKGROUND | FORMITEM_TITLE | FORMITEM_SOFTKEY);

    if (pEvent->base.evCode == EVT_MDL_FORM_CHANGE && dwItemMask) {
       RootForm_Update(me, dwItemMask, pEvent->piForm);
    }
 }

 static void RootForm_ShowFormWidget(IRootForm *po, IForm *piForm, boolean bShow, boolean bFocus)
 {
    DECL(RootForm);
    WidgetPos pos;
    IWidget *piWidget;

    if (!piForm)
       return;

    IFORM_GetWidget(piForm, WID_FORM, &piWidget);

    if (!piWidget)
       return;

    // Set visibility
    IROOTCONTAINER_GetPos(me->piContainer, piWidget, &pos);
    pos.bVisible = bShow;
    IROOTCONTAINER_SetPos(me->piContainer, piWidget, WIDGET_ZNORMAL, &pos);

    // and set focus to the widget
    if (bShow && bFocus) {
       IWIDGET_MoveFocus(FORM_WIDGET(me), piWidget);
    } else {
       IWIDGET_MoveFocus(FORM_WIDGET(me), WIDGET_FOCUS_NONE);
    }

    IWIDGET_Release(piWidget);
 }

 /** Activates a given form.  Previous form should have been
  deactivated before this is called with bActivate set
  */
 static void RootForm_ActivateForm(IRootForm *po, IForm *piForm, boolean bActivate)
 {
    DECL(RootForm);

    if (!piForm)
       return;

    if (bActivate) {
       // Undo the currently known active widget
       RELEASEIF(me->piActiveWidget);
       IFORM_GetWidget(piForm, WID_FORM, &me->piActiveWidget);
       // Then go update all the items except the forms widget as this is not the
       // form updating its own widget. Need to update first since theme information
       // affect client area which affects form activation
       RootForm_Update(me, FORMITEM_ALL & ~FORMITEM_WIDGET, piForm);
       // then activate
       IFORM_Activate(piForm);
    } else {
       IFORM_Deactivate(piForm);
    }
 }

 static int RootForm_GetFormIndex(RootForm *me, IForm **ppiForm)
 {
    IForm *piForm;
    int nrForms;

    nrForms = IVECTORMODEL_Size(me->piForms);

    if (nrForms > ) {

       if (*ppiForm == FORM_LAST || *ppiForm == FORM_DEFAULT) {

          IVECTORMODEL_GetAt(me->piForms, nrForms - , (void **)ppiForm);
          return nrForms - ;

       } else if (*ppiForm == FORM_FIRST) {

          IVECTORMODEL_GetAt(me->piForms, , (void **)ppiForm);
          return ;

       } else {

          int i;
          for (i = ; i < nrForms; i++) {
             IVECTORMODEL_GetAt(me->piForms, i, (void **)&piForm);
             if (piForm == *ppiForm)
                return i;
          }

       }
    }

    return -;
 }

 static __inline int RootForm_GetFormInsertionIndex(RootForm *me, IForm **ppiForm)
 {
    int delta;

    if (*ppiForm == FORM_FIRST)
       return ;

    if (*ppiForm == FORM_LAST || *ppiForm == FORM_DEFAULT) {
       delta = ;
    } else {
       delta = ;
    }

    return RootForm_GetFormIndex(me, ppiForm) + delta;
 }

 static void RootForm_StackChange(IRootForm *po)
 {
    DECL(RootForm);
    IForm* piTopForm = IROOTFORM_GetTopForm(po);

    LISTENER_Cancel(&me->mlFormActive);
    LISTENER_Cancel(&me->mlFormTopmostNonPopup);

    // If there are still forms on the stack, then we need to set up several things:
    //   1. The topmost form is the active form
    //   2. All other forms are not active
    //   3. The topmost form is being listened to via mlFormActive
    //   4. The topmost non-popup form is being listened to via mlFormTopmostNonPopup
    //   5. The topmost non-popup form and all popup forms on top of it are shown
    //   6. Forms below the topmost non-popup form are now shown
    if (piTopForm)
    {
       boolean bFoundTopmostNonPopup = FALSE;
       IModel* piModel = NULL;
       IForm*  pif;

       // Logging stack change begin
       BUIT_LOG("FORMS EVT: Stack Change Starting...", );

       // Need to deal with the non-active forms first, then the active form
       for (pif = piTopForm; pif; pif = IROOTFORM_GetForm(po, pif, FALSE, FALSE))
       {
          boolean bPopup;

          bPopup = IFORM_GetIsPopup(pif);
          IFORM_GetFormModel(pif, &piModel);
          if (piModel)
          {
             if (pif != piTopForm)
             {
                RootForm_ShowFormWidget(po, pif, (boolean)(bFoundTopmostNonPopup? FALSE : TRUE), FALSE);
                if (IFORM_IsActive(pif))
                {
                   RootForm_ActivateForm(po, pif, FALSE);
                }
             }

             if (!bPopup && !bFoundTopmostNonPopup)
             {
                IMODEL_AddListenerEx(piModel, &me->mlFormTopmostNonPopup, (PFNLISTENER)RootForm_UpdateTopmostNonPopupListenerCB, me);
                if (pif != piTopForm)
                   // Only update if not the topmost form since the
                   // Activate below applies theme again The topmost
                   // non-popup (but not the top!) influences the
                   // background, title ans associated themes
                   RootForm_Update(me, FORMITEM_BACKGROUND | FORMITEM_TITLE | FORMITEM_THEME_BASENAME, pif);
                bFoundTopmostNonPopup = TRUE;
             }
          }
          RELEASEIF(piModel);
       }

       RootForm_ActivateForm(po, piTopForm, TRUE);
       RootForm_ShowFormWidget(po, piTopForm, TRUE, TRUE);
       IFORM_GetFormModel(piTopForm, &piModel);
       if (piModel)
          IMODEL_AddListenerEx(piModel, &me->mlFormActive, (PFNLISTENER)RootForm_UpdateActiveListenerCB, me);
       RELEASEIF(piModel);

       // Log that the form is about to be activated - all theme stuff has happened by now)
       BUIT_LOG("FORMS EVT: Stack Change Finished", );

    }

     // Notify change in stack
    Form_Notify(ROOTFORM_TO_FORM(me), FORMITEM_STACK);
 }

 int RootForm_InsertForm(IRootForm *po, IForm *piForm, IForm *pifBefore)
 {
    DECL(RootForm);
    IWidget *piWidget = ;
    IWidget *piwBefore = ;
    IForm *pifCurrent;
    int nrForms, formIndex, nErr;

    if (!piForm)
       return EBADPARM;

    // Make sure we can insert, get the index we want to insert at
    formIndex = RootForm_GetFormInsertionIndex(me, &pifBefore);

    if (formIndex < )
       return EBADPARM;

    nrForms = IVECTORMODEL_Size(me->piForms);
    pifCurrent = IROOTFORM_GetTopForm(po);

    // Get widget to insert
    IFORM_GetWidget(piForm, WID_FORM, &piWidget);

    // Get widget insertion point.
    if (formIndex == nrForms || !nrForms) {
       piwBefore = WIDGET_ZTOPMOST;
    } else if (pifBefore == FORM_FIRST) {
       if (me->piBackground != NULL) {

          // If we have a background widget, try to insert the form's widget
          // above the background widget
          piwBefore = IROOTCONTAINER_GetWidget(me->piContainer, me->piBackground, TRUE, FALSE);
          if (piwBefore) {
             // Add a reference, so it can be released below.
             IWIDGET_AddRef(piwBefore);
          }
       } 

       if (!piwBefore) {
          // No background widget, insert the form's widget at the bottom.
          piwBefore = WIDGET_ZBOTTOMMOST;
       }

    } else {
       IFORM_GetWidget(pifBefore, WID_FORM, &piwBefore);
    }

    // Make sure we have space for the new form
    nErr = IVECTORMODEL_EnsureCapacity(me->piForms, MAX(FORMSTACK_MIN, nrForms + ), FORMSTACK_GROW);

    // Now insert
    if (!nErr && piWidget && piwBefore) {
       WidgetPos pos;

       // Not really needed here since Activate does this to, but since
       // we need to give a position on insert we may as well do it
       // right
       pos.x = me->rcClient.x;
       pos.y = me->rcClient.y;
       pos.bVisible = (piwBefore == WIDGET_ZTOPMOST);

       // Insert widget into widget stack
       nErr = IROOTCONTAINER_Insert(me->piContainer, piWidget, piwBefore, &pos);
    }

    if (!nErr) {
       char* pTheme = ;

       // Add form to formstack
       IVECTORMODEL_InsertAt(me->piForms, formIndex, piForm);
       IFORM_AddRef(piForm);

       // Set rootform
       IFORM_SetProperty(piForm, FID_ROOT, (uint32)po);

       // Log info
       IFORM_GetThemeBaseName(ROOTFORM_TO_IFORM(me), &pTheme);
       pTheme = (pTheme) ? pTheme : "(None)";

       BUIT_LOG("FORMS EVT: Insert Set Theme Started for %s", pTheme);

       // Set theme on new form
       IFORM_ApplyTheme(piForm);

       BUIT_LOG("FORMS EVT: Insert Set Theme Finished for %s", pTheme);
       //RootForm_Update(me, FORMITEM_THEME, piForm);

       RootForm_StackChange(po);

 }

    RELEASEIF(piWidget);
    if (piwBefore != WIDGET_ZTOPMOST && piwBefore != WIDGET_ZBOTTOMMOST)
       RELEASEIF(piwBefore);
    return nErr;
 }

 int RootForm_RemoveForm(IRootForm *po, IForm *piForm)
 {
    DECL(RootForm);
    IWidget *piWidget = ;
    IForm *piF = ;
    int nrForms = ;
    int formIndex;
    boolean bOnlyPopups = ;

    if (me->piForms)
       nrForms = IVECTORMODEL_Size(me->piForms);

    if (piForm == FORM_ALL) {
       while (nrForms > ) {
          IROOTFORM_RemoveForm(po, FORM_LAST);
          nrForms = IVECTORMODEL_Size(me->piForms);
       }

    } else {
       formIndex = RootForm_GetFormIndex(me, &piForm);

       if (formIndex < )
          return EBADPARM;

       IFORM_GetWidget(piForm, WID_FORM, &piWidget);

       if (piWidget) {
          IROOTCONTAINER_Remove(me->piContainer, piWidget);
       }

       // Hide form widget
       RootForm_ShowFormWidget(po, piForm, FALSE, FALSE);
       // Deactivate form
       RootForm_ActivateForm(po, piForm, FALSE);
       // Tell it of rootform departure
       IFORM_SetProperty(piForm, FID_ROOT, );
       // Delete it from the stack
       IVECTORMODEL_DeleteAt(me->piForms, formIndex);

       RootForm_StackChange(po);

       RELEASEIF(piWidget);

       // Now many forms do we now have?
       nrForms = IVECTORMODEL_Size(me->piForms);
    }

    // Cycle through remaining forms to determine type
    for (piF = IROOTFORM_GetTopForm(po); piF && bOnlyPopups; piF = IROOTFORM_GetForm(po, piF, FALSE, FALSE))
    {
       bOnlyPopups &= IFORM_GetIsPopup(piF);
    }  

    if (( == nrForms) || bOnlyPopups)
    {
       // If we don't have any more forms, or the only forms we do have are popups,
       // ensure the title has been cleaned (the title memory is owned by the last full screen form,
       // which may no longer exist).
       if (me->piTitle) {
          // Release image. Text is owned by form
          RELEASEIF(me->titleInfo.piImage);
          me->titleInfo.pwText = NULL;

          // Set title info
          IWIDGET_SetImageStaticInfo(me->piTitle, &me->titleInfo, );
       }
    }

    if ( == nrForms) {

       // There are no more forms, ensure the softkey labels
       // have been cleaned (the softkey memory is owned by the form, which may no
       // longer exist).
       if (me->piSoftkeys) {
          IWidget *piKey = NULL;

          (void) IWIDGET_GetSoftkey(me->piSoftkeys, PROP_SOFTKEY1, &piKey);
          if (piKey) {
             IWIDGET_SetText(piKey, NULL, );
             IWIDGET_Release(piKey);
             piKey = NULL;
          }

          (void) IWIDGET_GetSoftkey(me->piSoftkeys, PROP_SOFTKEY2, &piKey);
          if (piKey) {
             IWIDGET_SetText(piKey, NULL, );
             IWIDGET_Release(piKey);
             piKey = NULL;
          }

       }
    } else {
       RootForm_Update(me, FORMITEM_THEME_BASENAME, IROOTFORM_GetTopForm(po));
    }

    return AEE_SUCCESS;
 }

 void RootForm_GetClientRect(IRootForm *po, IXYContainer **ppo, AEERect *rc)
 {
    DECL(RootForm);

    if (rc) {
       *rc = me->rcClient;
    }

    if (ppo && me->piContainer) {
       *ppo = IROOTCONTAINER_TO_IXYCONTAINER(me->piContainer);
       IROOTCONTAINER_AddRef(me->piContainer);
    }
 }

 IForm *RootForm_GetForm(IRootForm *po, IForm *pifRef, boolean bNext, boolean bWrap)
 {
    DECL(RootForm);
    IForm *piForm = ;
    int nrForms, formIndex;

    if (me->piForms == NULL)
       return NULL;

    nrForms = IVECTORMODEL_Size(me->piForms);

    if (pifRef == NULL) {
       formIndex = bNext ?  : nrForms - ;
       IVECTORMODEL_GetAt(me->piForms, formIndex, (void **)&piForm);
       return piForm;
    }

    formIndex = RootForm_GetFormIndex(me, &pifRef);

    if (formIndex < )
       return NULL;

    formIndex += bNext ?  : -;
    if (formIndex < ) {
       formIndex = bWrap ? nrForms -  : -;
    } else if (formIndex >= nrForms) {
       formIndex = bWrap ?  : - ;
    }

    if (formIndex < )
       return NULL;

    IVECTORMODEL_GetAt(me->piForms, formIndex, (void **)&piForm);
    return piForm;
 }

 int RootForm_ResolveForm(IRootForm *po, char const *szFormUrl, IForm **ppiForm)
 {
    DECL(RootForm);
    IWebUtil *piWebUtil = ;
    AEECLSID formClsId;
    int result;
    UrlParts parts;
    char *path = ;

    if (!ppiForm || !szFormUrl)
       return EBADPARM;

    // Assume failure
    *ppiForm = ;

    // Parse the URL
    result = ISHELL_CreateInstance(FORM_SHELL(me), AEECLSID_WEBUTIL, (void **) &piWebUtil);

    if (result == )
       result = IWEBUTIL_ParseUrl(piWebUtil, szFormUrl, &parts);

       // Check the scheme
    if (result ==
        && (!UP_HASSCHM(&parts) || STRNCMP(parts.cpcSchm,FORM_URL_SCHEME,sizeof(FORM_URL_SCHEME)-)))
        result = ESCHEMENOTSUPPORTED;

       // Do we have a path?
    if (result ==
        && (!UP_HASPATH(&parts) || UP_PATHLEN(&parts) <= ))
       result = ESCHEMENOTSUPPORTED;

    // Extract the path (we need it to be NULL terminated)
    if (result ==
        &&  == (path = MALLOC(UP_PATHLEN(&parts)+)))
       result = ENOMEMORY;

    if (result == ) {
       STRNCPY(path, parts.cpcHost, UP_PATHLEN(&parts)+);

       // Does a handler exist for this path, of type AEEIID_FORM?
       if ( == (formClsId = ISHELL_GetHandler(FORM_SHELL(me), AEEIID_FORM, path)))
          // Nope...
          result = ESCHEMENOTSUPPORTED;
    }

    if (result == )
       // Got the actual class id, lets create the form
       result = ISHELL_CreateInstance(FORM_SHELL(me), formClsId, (void **) ppiForm);

    //
    // TODO: We could use IWEBUTIL_ParseFormFields() to parse parts.cpcSrch
    //       for known Form properties and apply them here...

    RELEASEIF(piWebUtil);
    FREEIF(path);

    return result;
 }

 void RootForm_Dtor(RootForm *me)
 {
    IROOTFORM_RemoveForm(ROOTFORM_TO_IROOTFORM(me), FORM_ALL);

    RELEASEIF(me->piTitle);
    RELEASEIF(me->piSoftkeys);
    RELEASEIF(me->piContainer);
    RELEASEIF(me->piBackground);
    RELEASEIF(me->titleInfo.piImage);
    RELEASEIF(me->piForms);
    RELEASEIF(me->piActiveWidget);
    RELEASEIF(me->piThemeFile);
    FREEIF(me->themeFile);

    Form_Dtor(&me->base);
 }

 uint32 RootForm_Release(IRootForm *po)
 {
    DECL(RootForm);

    if (FORM_NREFS(me) == )
       RootForm_Dtor(me);

    return Form_Release(IROOTFORM_TO_IFORM(po));
 }

 int RootForm_QueryInterface(IRootForm *po, AEECLSID clsid, void **ppo)
 {
    if (clsid == AEEIID_ROOTFORM) {
       *ppo = po;
       Form_AddRef(IROOTFORM_TO_IFORM(po));
       return AEE_SUCCESS;
    }

    return Form_QueryInterface(IROOTFORM_TO_IFORM(po), clsid, ppo);
 }

 int RootForm_Construct(RootForm *me, AEEVTBL(IRootForm) *pvt, IModule *piModule, IShell *piShell)
 {
    int result;
    WExtent extent;
    WidgetPos pos;
    IDisplay *piDisplay = ;
    ICanvas *piCanvas = ;

    Form_Ctor(&me->base, (AEEVTBL(IForm) *)pvt, piModule, piShell,
              (PFNHANDLER)RootForm_HandleEvent);

    pos.x = ;
    pos.y = ;
    pos.bVisible = TRUE;
    SETWEXTENT(&extent, , );

    // Form overrides
    pvt->Release         = RootForm_Release;
    pvt->QueryInterface  = RootForm_QueryInterface;
    // RootForm definitions
    pvt->InsertForm      = RootForm_InsertForm;
    pvt->RemoveForm      = RootForm_RemoveForm;
    pvt->GetClientRect   = RootForm_GetClientRect;
    pvt->GetForm         = RootForm_GetForm;
    pvt->ResolveForm     = RootForm_ResolveForm;

    result = ISHELL_CreateInstance(piShell, AEECLSID_VECTORMODEL, (void **)&me->piForms);

    if (result == ) {
       IVECTORMODEL_SetPfnFree(me->piForms, (PFNNOTIFY)RootForm_FreeFormEntry);

       result = ISHELL_CreateInstance(piShell, AEECLSID_DISPLAY, (void **)&piDisplay);
    }

    if (result == )
       result = ISHELL_CreateInstance(piShell, AEECLSID_ROOTCONTAINER, (void **)&me->piContainer);

    if (result == )
       result = IROOTCONTAINER_QueryInterface(me->piContainer, AEEIID_WIDGET, (void **)&me->base.piWidget);

    if (result == )
       result = ISHELL_CreateInstance(piShell, AEECLSID_RESFILE, (void **)&me->piThemeFile);

    if (result == )
       result = ISHELL_CreateInstance(piShell, AEECLSID_IMAGEWIDGET, (void **)&me->piBackground);

    if (result == ) {
       IWIDGET_SetFlags(me->piBackground, IDF_ALIGN_RIGHT | IDF_ALIGN_BOTTOM);

       // Insert, extent will be fixed up in SetDisplay below
       result = IROOTCONTAINER_Insert(me->piContainer, me->piBackground, WIDGET_ZBOTTOMMOST, &pos);
    }

    if (result == )
       // Construct title
       result = ISHELL_CreateInstance(piShell, AEECLSID_IMAGESTATICWIDGET, (void **)&me->piTitle);

    if (result == ) {
       extent.height = ;
       // Set title font to bold by default.  Apps and themes can override it.
       IWIDGET_SetFontClass(me->piTitle, AEECLSID_FONTSYSBOLD);

       IWIDGET_SetShadowOffsetY(me->piTitle, );
       IWIDGET_SetBorderWidth(me->piTitle, );
       IWIDGET_SetExtent(me->piTitle, &extent);
       // Add to container
       result = IROOTCONTAINER_Insert(me->piContainer, me->piTitle, WIDGET_ZTOPMOST, &pos);
    }

    if (result == )
       // Construct Softkeys
       result = ISHELL_CreateInstance(piShell, AEECLSID_SOFTKEYWIDGET, (void **)&me->piSoftkeys);

    if (result == ) {
       IWIDGET_SetShadowOffsetY(me->piSoftkeys, -);
       IWIDGET_SetBorderWidth(me->piSoftkeys, );
       IWIDGET_SetExtent(me->piSoftkeys, &extent);
       IWIDGET_SetLeftPadding(me->piSoftkeys, );
       IWIDGET_SetRightPadding(me->piSoftkeys, );

       // Insert at 0, 0. Correct positioning will happen in SetDisplay
       result = IROOTCONTAINER_Insert(me->piContainer, me->piSoftkeys, WIDGET_ZTOPMOST, &pos);
    }

    if (result == )
       result = RootForm_SetDisplay(me, piDisplay);

    if (result == ) {
       char* pTheme = ;
       IFORM_SetThemeBaseName(ROOTFORM_TO_IFORM(me), "Root");

       IFORM_GetThemeBaseName(ROOTFORM_TO_IFORM(me), &pTheme);
       pTheme = (pTheme) ? pTheme : "(None)";

       BUIT_LOG("FORMS EVT: Construct Set Theme Started for %s", pTheme);

       IROOTFORM_SetThemeFileName(ROOTFORM_TO_IROOTFORM(me), "theme.bar");

       BUIT_LOG("FORMS EVT: Construct Set Theme Finished for %s", pTheme);

    } else {
       RootForm_Dtor(me);
    }

    RELEASEIF(piDisplay);
    RELEASEIF(piCanvas);

    return result;
 }

 int RootForm_New(IRootForm **ppo, IModule *piModule, IShell *piShell)
 {
    RootForm *me = MALLOCREC_VTBL(RootForm, IRootForm);
    int result;

    *ppo = (IRootForm *)me;

    if (!me)
       return ENOMEMORY;

    result = RootForm_Construct(me, GETVTBL(me, IRootForm), piModule, piShell);

    if (result != ) {
       *ppo = NULL;
       FREE(me);
    }

    return result;
 }

小结：

• 注释应该准确易懂，防止二义性，错误的注释有害无利
• 注释是对代码的提示，避免臃肿和喧宾夺主
• 一目了然的代码避免加注释
• 不要用缩写来注释代码，这样可能会产生误解
• 注释用于阐述原因和意图而不是描述程序的运行过程