【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 个月后的你。

  《编写可读性代码的艺术》
  

以上内容参考狄泰软件学院系列课程，请大家保护原创！