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 个月后的你。
推荐书籍:《编写可读性代码的艺术》

内容参考狄泰软件学院系列课程,如有侵权,请联系作者删除!感谢~

已标记关键词 清除标记
©️2020 CSDN 皮肤主题: 编程工作室 设计师:CSDN官方博客 返回首页