1.7　實例分析

1.7.1　PurC函數庫頭文件

下面通過查看筆者維護的開源HVML解釋器PurC的purc.h頭文件中的部分內容，來對本章所述的優良編碼風格做進一步的解釋。

首先是一段Doxygen格式的注釋，其中包含了文件名、作者、日期、簡介、版權聲明等信息。注意，Doxygen格式的注釋一般以/**開始。

/**
 * @file purc.h
 * @author Vincent Wei
 * @date 2021/07/02
 * @brief The main header file of PurC.
 *
 * Copyright (C) 2021, 2022 FMSoft
 *
 * This file is a part of PurC (short for Purring Cat), an HVML interpreter.
 * Licensed under LGPLv3+.
 */

之后，作為PurC函數庫的主頭文件，其中包含了其他必要的系統頭文件以及PurC函數庫的其他頭文件。然后是一個結構體的定義，該結構體被定義為一個新的數據類型，同時使用Doxygen格式的注釋來描述其成員的含義。

/**
 * purc_instance_extra_info:
 *
 * The structure defines the extra information for a new PurC instance.
 */
typedef struct purc_instance_extra_info {
    /**
     * ...
     */
    purc_rdrcomm_k  renderer_comm;
　
    /**
     * ...
     */
    const char      *renderer_uri;
　
    /** The SSL certification if using Secured WebSocket. */
    const char      *ssl_cert;
　
    /** The SSL key if using Secured WebSocket. */
    const char      *ssl_key;
　
    /** The default workspace of this instance. */
    const char      *workspace_name;
　
    /** The title of the workspace. */
    const char      *workspace_title;
　
    /**
     * ...
     */
    const char      *workspace_layout;
} purc_instance_extra_info;

我們可以清晰地看到，PurC函數庫的接口使用了K&R命名法。注意上述結構體中的purc_rdrcomm_k renderer_comm成員，從類型名使用_k后綴可以看出，該成員是一個枚舉量，對應的枚舉類型則定義在另一個頭文件（purc-pcrdr.h）中：

/* Renderer communication types */
typedef enum {
    PURC_RDRCOMM_HEADLESS  = 0,
#define PURC_RDRCOMM_NAME_HEADLESS      "HEADLESS"
    PURC_RDRCOMM_THREAD,
#define PURC_RDRCOMM_NAME_THREAD        "THREAD"
    PURC_RDRCOMM_SOCKET,
#define PURC_RDRCOMM_NAME_SOCKET        "SOCKET"
    PURC_RDRCOMM_HIBUS,
#define PURC_RDRCOMM_NAME_HIBUS         "HIBUS"
} purc_rdrcomm_k;

回到purc.h頭文件。再往下是宏定義：

#define PURC_HAVE_UTILS         0x0001
#define PURC_HAVE_DOM           0x0002
#define PURC_HAVE_HTML          0x0004
#define PURC_HAVE_XML           0x0008
#define PURC_HAVE_VARIANT       0x0010
#define PURC_HAVE_EJSON         0x0020
#define PURC_HAVE_FETCHER       0x0200
#define PURC_HAVE_FETCHER_R     0x0400
#define PURC_HAVE_ALL (           \
        PURC_HAVE_UTILS         | \
        PURC_HAVE_DOM           | \
        PURC_HAVE_HTML          | \
        PURC_HAVE_XML           | \
        PURC_HAVE_VARIANT       | \
        PURC_HAVE_EJSON         | \
        PURC_HAVE_FETCHER       | \
        PURC_HAVE_FETCHER_R)
　
#define PURC_MODULE_UTILS      (PURC_HAVE_UTILS)
#define PURC_MODULE_DOM        (PURC_MODULE_UTILS    | PURC_HAVE_DOM)
#define PURC_MODULE_HTML       (PURC_MODULE_DOM      | PURC_HAVE_HTML)
#define PURC_MODULE_XML        (PURC_MODULE_DOM      | PURC_HAVE_XML)
#define PURC_MODULE_VARIANT    (PURC_MODULE_UTILS    | PURC_HAVE_VARIANT)
#define PURC_MODULE_EJSON      (PURC_MODULE_VARIANT  | PURC_HAVE_EJSON)
#define PURC_MODULE_ALL         0xFFFF

所有的宏都采用下畫線連接的全大寫單詞形式，并使用PURC_作為前綴；代碼行嚴守了“80列”這條紅線，并通過空行、續行和適當的縮進，讓排版整齊，使得整個代碼清晰易讀。

下面查看其中的3個函數接口：前兩個用于初始化一個PurC實例，第三個用于清理一個PurC實例。

PCA_EXPORT int
purc_init_ex(unsigned int modules,
        const char *app_name, const char *runner_name,
        const purc_instance_extra_info *extra_info);
　
static inline int purc_init(const char *app_name, const char *runner_name,
        const purc_instance_extra_info *extra_info)
{
    return purc_init_ex(PURC_MODULE_ALL, app_name, runner_name, extra_info);
}
　
PCA_EXPORT bool
purc_cleanup(void);

這3個函數的原型定義符合本章所討論的編碼風格。比如，purc_init_ex()和purc_init()兩個函數均具有purc_前綴，表示指針的星號出現在形參名稱的前面；為嚴守“80列”這條紅線，函數原型聲明中的參數列表被分行書寫；等等。作為PurC函數庫的公開接口，原頭文件中包含了對以上函數的接口描述。

注意purc_init()函數被定義為調用purc_init_ex()函數的內聯函數，因而使用static inline關鍵詞來修飾其原型。而_ex后綴通常用于表示擴展（extended）；也就是說，purc_init_ex()函數是purc_init()函數的擴展版本。