【C】 12_註釋符號

實例分析： 初探註釋規則

#include <stdio.h>

int main()
{
    int /*...*/i;
    
    char* s = "abcdefgh    //hijklm";
    
    // Is it a \
    valid comment?
    
    in/*...*/t i;
    
    return 0;
}

輸出：
test.c: In function ‘main’:
test.c:12: error: ‘in’ undeclared (first use in this function)
test.c:12: error: (Each undeclared identifier is reported only once
test.c:12: error: for each function it appears in.)
test.c:12: error: expected ‘;’ before ‘t’

註釋規則

• 編譯器在編譯過程當中使用空格替代整個註釋
• 字符串字面量中的 // 和 /。。。/ 不表明註釋符號
• /....../ 型註釋不能被嵌套

有趣的問題

• 你以爲 y=x/*p 是什麼意思？

做者本意：把 x 除以 *p 的結果賦值給 y。

編譯器： 將 /* 做爲一段註釋的開始，把 /* 後的內容都當成註釋內容，直到 */ 出現爲止。

在編譯器看來，註釋和其它程序元素是平等的。所以，做爲工程是不能輕視註釋。

傻瓜型註釋

void code()
{
    r = n / 2;                    // r 是 n 的一半
    while( ( r - n / r) <= t )    // 循環，僅當 r - n / r 不大於 t
    {
    }
    
    r = r + n * t;                // 對變量 r 進行賦值
    
    n++;                          // 變量 n 自增 1
    
    return 0;
}

註釋用於闡明緣由和意圖而不是描述程序的運行過程！

迷惑型的註釋

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

0x723 = 1827 , 貝多芬逝世

寫註釋不是曬心情，必須無二義性，起到對代碼進行提示的做用，避免使用縮寫！

忽悠型註釋

int main()
{
    // ... ...
    // ... ...
    
    // Bob 07/24/1995
    /* 我知道這個問題很難解決
     * 並且如今必須依賴於這個 contains 函數
     * 但我之後會用一種更加直觀優雅有意義的方式重寫這段代碼
     * 如今這麼作只是因爲時間緊迫，但我必定會解決
     */
     if( contains(s, "error") )
     {
         exit(1);
     }
     
     return 0;
}

註釋是對代碼的提示，避免臃腫和喧賓奪主！

搞笑型註釋

//                       .::::.
//                     .::::::::.
//                    :::::::::::
//                 ..:::::::::::'
//              '::::::::::::'
//                .::::::::::
//           '::::::::::::::..
//                ..::::::::::::.
//              ``::::::::::::::::
//               ::::``:::::::::'        .:::.
//              ::::'   ':::::'       .::::::::.
//            .::::'      ::::     .:::::::'::::.
//           .:::'       :::::  .:::::::::' ':::::.
//          .::'        :::::.:::::::::'      ':::::.
//         .::'         ::::::::::::::'         ``::::.
//     ...:::           ::::::::::::'              ``::.
//    ```` ':.          ':::::::::'                  ::::..
//                       '.:::::'                    ':'````..

實例分析： 漂亮的代碼註釋

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

  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
==================================================================================*/
// 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 = 0;

   // 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, 0);
   }

   // 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, 0);
         }
         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, 0);
         }
      }
      RELEASEIF(piKey);
   }

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

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

}

小結

• 註釋應該準確易懂，防止二義性，錯誤的註釋有害無利
• 註釋是對代碼的提示，避免臃腫和喧賓奪主
• 一目瞭然的代碼避免加註釋
• 不要用縮寫來寫代碼，這樣可能會產生誤解
• 註釋用於闡述緣由和意圖而不是描述程序的運行過程

補充： 代碼是寫給別人看的，別人可能包括 6 個月後的你。

《編寫可讀性代碼的藝術》

以上內容參考狄泰軟件學院系列課程，請你們保護原創！