前言

很多事不深入以為自己懂了，但真正用到項(xiàng)目上，才發(fā)現(xiàn)了問(wèn)題。曾以為自己寫C語(yǔ)言已經(jīng)輕車熟路了，特別是對(duì)軟件文件的工程管理上，因?yàn)樾睦飳?duì)自己的代碼編寫風(fēng)格還是有自信的。(畢竟剛畢業(yè)時(shí)老大對(duì)我最初的訓(xùn)練就是編碼格式的規(guī)范化處理)

曾以為，一個(gè).c文件對(duì)應(yīng)一個(gè).h文件,.c文件只包含它自身的.h文件就好，若.c文件中用到其他文件中的內(nèi)容,則.h文件把用到的頭文件包含進(jìn)來(lái)就可以了。自己貌似一直秉承這個(gè)理念在進(jìn)行代碼編寫（好可怕）。工程文件數(shù)量小時(shí)，這種理念貌似看不出問(wèn)題，但隨著工程文件數(shù)量越來(lái)越多，我發(fā)現(xiàn)自己這種思路有了弊端：頭文件互相包含，導(dǎo)致編譯時(shí)自以為有些宏變量聲明了，它就能起作用，但實(shí)際測(cè)試發(fā)現(xiàn)這種方式編碼后，有些聲明的宏沒(méi)能起到作用。

經(jīng)過(guò)領(lǐng)導(dǎo)及同事的指正，自己才明白原有的代碼編寫習(xí)慣不正確。應(yīng)該秉承.c文件對(duì)應(yīng)的.h文件只包含頭文件里用到的其它文件的頭文件,任何非必須的.h文件不要包含；而.c文件里面要包含用到的所有.h文件。這樣寫即使存在.c文件內(nèi)頭文件重復(fù)包含也不傷大雅。

語(yǔ)言描述有時(shí)太抽象，還是符號(hào)舉例說(shuō)明下：假如有兩個(gè).c文件分別為A.c和B.c，自然它們都有各自的A.h和B.h文件。

原有的思路：A.c里面只有一個(gè)#include "A.h",而A.h所包含的就是一大堆如B.h,C.h,D.h.....文件，因?yàn)锳.c文件里面要用到B.h,C.h,D.h里面的內(nèi)容。如圖一所示。

新思路：A.h里面只包含A.h所寫內(nèi)容要用到的.h文件,很多時(shí)候A.h里面無(wú)需任何.h文件.而在A.c文件內(nèi)就要寫成 #include "B.h" #include "C.h" #include "D.h"。而且兩個(gè)文件的.c文件在頭文件包含上可以互相包含。如圖二所示。

項(xiàng)目中遇到的這個(gè)頭文件包含問(wèn)題導(dǎo)致我重新搜索資料進(jìn)行該問(wèn)題的深入了解，故下文是通過(guò)網(wǎng)絡(luò)資源的搜查及加上自己對(duì)它的理解，進(jìn)行了相關(guān)內(nèi)容的整理，希望對(duì)感興趣的小伙伴有所幫助。

背景

對(duì)于C語(yǔ)言來(lái)說(shuō)，頭文件的設(shè)計(jì)體現(xiàn)了大部分的系統(tǒng)設(shè)計(jì)。 不合理的頭文件布局是編譯時(shí)間過(guò)長(zhǎng)的根因，不合理的頭文件實(shí)際上不合理的設(shè)計(jì)。

依賴

特指編譯依賴。若x.h包含了y.h，則稱作x依賴y。依賴關(guān)系會(huì)進(jìn)行傳導(dǎo)，如x.h包含y.h，而y.h又包含了z.h，則x通過(guò)y依賴了z。依賴將導(dǎo)致編譯時(shí)間的上升。雖然依賴是不可避免的，也是必須的，但是不良的設(shè)計(jì)會(huì)導(dǎo)致整個(gè)系統(tǒng)的依賴關(guān)系無(wú)比復(fù)雜，使得任意一個(gè)文件的修改都要重新編譯整個(gè)系統(tǒng)，導(dǎo)致編譯時(shí)間巨幅上升。

在一個(gè)設(shè)計(jì)良好的系統(tǒng)中， 修改一個(gè)文件，只需要重新編譯數(shù)個(gè)，甚至是一個(gè)文件。

某產(chǎn)品曾經(jīng)做過(guò)一個(gè)實(shí)驗(yàn)，把所有函數(shù)的實(shí)現(xiàn)通過(guò)工具注釋掉，其編譯時(shí)間只減少了不到10%，究其原因，在于A包含B， B包含C， C包含D，最終幾乎每一個(gè)源文件都包含了項(xiàng)目組所有的頭文件，從而導(dǎo)致絕大部分編譯時(shí)間都花在解析頭文件上。

某產(chǎn)品更有一個(gè)“優(yōu)秀實(shí)踐”，用于將.c文件通過(guò)工具合并成一個(gè)比較大的.c文件，從而大幅度提高編譯效率。其根本原因還是在于通過(guò)合并.c文件減少了頭文件解析次數(shù)。但是，這樣的“優(yōu)秀實(shí)踐”是對(duì)合理劃分.c文件的一種破壞。

大部分產(chǎn)品修改一處代碼，都得需要編譯整個(gè)工程，對(duì)于TDD之類的實(shí)踐，要求對(duì)于模塊級(jí)別的編譯時(shí)間控制在秒級(jí)，即使使用分布式編譯也難以實(shí)現(xiàn)，最終仍然需要合理的劃分頭文件、以及頭文件之間的包含關(guān)系， 從根本上降低編譯時(shí)間。

《google C++ Style Guide》 1.2 頭文件依賴 章節(jié)也給出了類似的闡述：

若包含了頭文件aa.h，則就引入了新的依賴：一旦aa.h被修改，任何直接和間接包含aa.h代碼都會(huì)被重新編譯。如果aa.h又包含了其他頭文件如bb.h，那么bb.h的任何改變都將導(dǎo)致所有包含了aa.h的代碼被重新編譯，在敏捷開(kāi)發(fā)方式下，代碼會(huì)被頻繁構(gòu)建，漫長(zhǎng)的編譯時(shí)間將極大的阻礙頻繁構(gòu)建。因此，我們傾向于減少包含頭文件，尤其是在頭文件中包含頭文件，以控制改動(dòng)代碼后的編譯時(shí)間。

合理的頭文件劃分體現(xiàn)了系統(tǒng)設(shè)計(jì)的思想，但是從編程規(guī)范的角度看，仍然有一些通用的方法，用來(lái)合理規(guī)劃頭文件。本章節(jié)介紹的一些方法，對(duì)于合理規(guī)劃頭文件會(huì)有一定的幫助。

原則1.1：頭文件中適合放置接口的聲明，不適合放置實(shí)現(xiàn)。

說(shuō)明： 頭文件是模塊（ Module）或單元（ Unit）的對(duì)外接口。頭文件中應(yīng)放置對(duì)外部的聲明，如對(duì)外提供的函數(shù)聲明、宏定義、類型定義等。

• 內(nèi)部使用的函數(shù)（相當(dāng)于類的私有方法）聲明不應(yīng)放在頭文件中。
• 內(nèi)部使用的宏、枚舉、結(jié)構(gòu)定義不應(yīng)放入頭文件中。
• 變量定義不應(yīng)放在頭文件中，應(yīng)放在.c文件中。
• 變量的聲明盡量不要放在頭文件中，亦即盡量不要使用全局變量作為接口 。變量是模塊或單元的內(nèi)部實(shí)現(xiàn)細(xì)節(jié)，不應(yīng)通過(guò)在頭文件中聲明的方式直接暴露給外部，應(yīng)通過(guò)函數(shù)接口的方式進(jìn)行對(duì)外暴露。

延伸閱讀材料： 《 C語(yǔ)言接口與實(shí)現(xiàn)》

原則1.2：頭文件應(yīng)當(dāng)職責(zé)單一。

說(shuō)明：頭文件過(guò)于復(fù)雜，依賴過(guò)于復(fù)雜是導(dǎo)致編譯時(shí)間過(guò)長(zhǎng)的主要原因。 很多現(xiàn)有代碼中頭文件過(guò)大，職責(zé)過(guò)多， 再加上循環(huán)依賴的問(wèn)題，可能導(dǎo)致為了在.c中使用一個(gè)宏，而包含十幾個(gè)頭文件。

某個(gè)頭文件不但定義了基本數(shù)據(jù)類型word，還包含了stdio.h syslib.h等等不常用的頭文件。如果工程中有10000個(gè)源文件，而其中100個(gè)源文件使用了stdio.h的printf，由于上述頭文件的職責(zé)過(guò)于龐大，而WORD又是每一個(gè)文件必須包含的，從而導(dǎo)致stdio.h/syslib.h等可能被不必要的展開(kāi)了9900次，大大增加了工程的編譯時(shí)間。

原則1.3：頭文件應(yīng)向穩(wěn)定的方向包含。

說(shuō)明： 頭文件的包含關(guān)系是一種依賴，一般來(lái)說(shuō)，應(yīng)當(dāng)讓不穩(wěn)定的模塊依賴穩(wěn)定的模塊，從而當(dāng)不穩(wěn)定的模塊發(fā)生變化時(shí)，不會(huì)影響（編譯）穩(wěn)定的模塊。

就我們的產(chǎn)品來(lái)說(shuō)，依賴的方向應(yīng)該是： 產(chǎn)品依賴于平臺(tái)，平臺(tái)依賴于標(biāo)準(zhǔn)庫(kù)。 某產(chǎn)品線平臺(tái)的代碼中已經(jīng)包含了產(chǎn)品的頭文件，導(dǎo)致平臺(tái)無(wú)法單獨(dú)編譯、發(fā)布和測(cè)試， 是一個(gè)非常糟糕的反例。

除了不穩(wěn)定的模塊依賴于穩(wěn)定的模塊外，更好的方式是兩個(gè)模塊共同依賴于接口，這樣任何一個(gè)模塊的內(nèi)部實(shí)現(xiàn)更改都不需要重新編譯另外一個(gè)模塊。在這里，我們假設(shè)接口本身是最穩(wěn)定的。

延伸閱讀材料： 編者推薦開(kāi)發(fā)人員使用“依賴倒置”原則，即由使用者制定接口，服務(wù)提供者實(shí)現(xiàn)接口，更具體的描述可以參見(jiàn)《 敏捷軟件開(kāi)發(fā)：原則、模式與實(shí)踐》 （ Robert C.Martin 著 鄧輝 譯 清華大學(xué)出版社2003年9月） 的第二部分“敏捷設(shè)計(jì)”章節(jié)。

規(guī)則1.1：每一個(gè).c文件應(yīng)有一個(gè)同名.h文件，用于聲明需要對(duì)外公開(kāi)的接口。

說(shuō)明： 如果一個(gè).c文件不需要對(duì)外公布任何接口，則其就不應(yīng)當(dāng)存在，除非它是程序的入口，如main函數(shù)所在的文件。

現(xiàn)有某些產(chǎn)品中，習(xí)慣一個(gè).c文件對(duì)應(yīng)兩個(gè)頭文件，一個(gè)用于存放對(duì)外公開(kāi)的接口，一個(gè)用于存放內(nèi)部需要用到的定義、聲明等，以控制.c文件的代碼行數(shù)。編者不提倡這種風(fēng)格。這種風(fēng)格的根源在于源文件過(guò)大，應(yīng)首先考慮拆分.c文件，使之不至于太大。另外，一旦把私有定義、聲明放到獨(dú)立的頭文件中，就無(wú)法從技術(shù)上避免別人include之，難以保證這些定義最后真的只是私有的。

本規(guī)則反過(guò)來(lái)并不一定成立。有些特別簡(jiǎn)單的頭文件，如命令I(lǐng)D定義頭文件，不需要有對(duì)應(yīng)的.c存在[a1] 。

示例：對(duì)于如下場(chǎng)景，如在一個(gè).c中存在函數(shù)調(diào)用關(guān)系：

void foo()
{
    bar();
}

void bar()
{
    Do something;
}

必須在foo之前聲明bar，否則會(huì)導(dǎo)致編譯錯(cuò)誤。

這一類的函數(shù)聲明，應(yīng)當(dāng)在.c的頭部聲明，并聲明為static的，如下：

static void bar();

void foo()
{
    bar();
}

void bar()
{
    Do something;
}

規(guī)則1.2：禁止頭文件循環(huán)依賴。

說(shuō)明： 頭文件循環(huán)依賴，指a.h包含b.h， b.h包含c.h， c.h包含a.h之類導(dǎo)致任何一個(gè)頭文件修改，都導(dǎo)致所有包含了a.h/b.h/c.h的代碼全部重新編譯一遍。而如果是單向依賴，如a.h包含b.h， b.h包含c.h，而c.h不包含任何頭文件，則修改a.h不會(huì)導(dǎo)致包含了b.h/c.h的源代碼重新編譯。

規(guī)則1.3：.c/.h文件禁止包含用不到的頭文件。

說(shuō)明： 很多系統(tǒng)中頭文件包含關(guān)系復(fù)雜，開(kāi)發(fā)人員為了省事起見(jiàn)，可能不會(huì)去一一鉆研，直接包含一切想到的頭文件，甚至有些產(chǎn)品干脆發(fā)布了一個(gè)god.h，其中包含了所有頭文件，然后發(fā)布給各個(gè)項(xiàng)目組使用，這種只圖一時(shí)省事的做法，導(dǎo)致整個(gè)系統(tǒng)的編譯時(shí)間進(jìn)一步惡化，并對(duì)后來(lái)人的維護(hù)造成了巨大的麻煩。

規(guī)則1.4：頭文件應(yīng)當(dāng)自包含。

說(shuō)明： 簡(jiǎn)單的說(shuō)，自包含就是任意一個(gè)頭文件均可獨(dú)立編譯。 如果一個(gè)頭文件包含某個(gè)頭文件，還要包含另外一個(gè)頭文件才能工作的話，就會(huì)增加交流障礙，給這個(gè)頭文件的用戶增添不必要的負(fù)擔(dān)[a2] 。

示例：

如果a.h不是自包含的，需要包含b.h才能編譯，會(huì)帶來(lái)的危害：每個(gè)使用a.h頭文件的.c文件，為了讓引入的a.h的內(nèi)容編譯通過(guò)，都要包含額外的頭文件b.h。額外的頭文件b.h必須在a.h之前進(jìn)行包含，這在包含順序上產(chǎn)生了依賴。

注意：該規(guī)則需要與“ .c/.h文件禁止包含用不到的頭文件”規(guī)則一起使用，不能為了讓a.h自包含，而在a.h中包含不必要的頭文件。 a.h要?jiǎng)倓偪梢宰园荒茉赼.h中多包含任何滿足自包含之外的其他頭文件。

規(guī)則1.5：總是編寫內(nèi)部#include保護(hù)符（ #define 保護(hù)）。

說(shuō)明：多次包含一個(gè)頭文件可以通過(guò)認(rèn)真的設(shè)計(jì)來(lái)避免。如果不能做到這一點(diǎn)，就需要采取阻止頭文件內(nèi)容被包含多于一次的機(jī)制。

通常的手段是為每個(gè)文件配置一個(gè)宏，當(dāng)頭文件第一次被包含時(shí)就定義這個(gè)宏，并在頭文件被再次包含時(shí)使用它以排除文件內(nèi)容。

所有頭文件都應(yīng)當(dāng)使用#define 防止頭文件被多重包含，命名格式為FILENAME_H，為了保證唯一性，更好的命名是
PROJECTNAME_PATH_FILENAME_H。

注：沒(méi)有在宏最前面加上““，即使用FILENAME_H代替FILENAME_H，是因?yàn)橐话阋?rdquo;“和”“開(kāi)頭的標(biāo)識(shí)符為系統(tǒng)保留或者標(biāo)準(zhǔn)庫(kù)使用，在有些靜態(tài)檢查工具中，若全局可見(jiàn)的標(biāo)識(shí)符以”_”開(kāi)頭會(huì)給出告警。

定義包含保護(hù)符時(shí)，應(yīng)該遵守如下規(guī)則：

1）保護(hù)符使用唯一名稱；

2）不要在受保護(hù)部分的前后放置代碼或者注釋。

示例：假定VOS工程的timer模塊的timer.h，其目錄為VOS/include/timer/timer.h,應(yīng)按如下方式保護(hù)：

#ifndef VOS_INCLUDE_TIMER_TIMER_H

#define VOS_INCLUDE_TIMER_TIMER_H

...

#endif

也可以使用如下簡(jiǎn)單方式保護(hù):

#ifndef TIMER_H

#define TIMER_H

..

#endif

例外情況：頭文件的版權(quán)聲明部分以及頭文件的整體注釋部分（如闡述此頭文件的開(kāi)發(fā)背景、使用注意事項(xiàng)等）可以放在保護(hù)符(#ifndef XX_H)前面。

規(guī)則1.6：禁止在頭文件中定義變量。

說(shuō)明：在頭文件中定義變量，將會(huì)由于頭文件被其他.c文件包含而導(dǎo)致變量重復(fù)定義。

規(guī)則1.7：只能通過(guò)包含頭文件的方式使用其他.c提供的接口，禁止在.c中通過(guò)extern的方式使用外部函數(shù)接口、變量[a3] 。

說(shuō)明：若a.c使用了b.c定義的foo()函數(shù)，則應(yīng)當(dāng)在b.h中聲明extern int foo(int input)；并在a.c中通過(guò)#include 來(lái)使用foo。禁止通過(guò)在a.c中直接寫extern int foo(int input);來(lái)使用foo，后面這種寫法容易在foo改變時(shí)可能導(dǎo)致聲明和定義不一致[a4] 。

規(guī)則1.8：禁止在extern “C”中包含頭文件。

說(shuō)明：在extern “C”中包含頭文件， 會(huì)導(dǎo)致extern “C”嵌套， Visual Studio對(duì)extern “C”嵌套層次有限制，嵌套層次太多會(huì)編譯錯(cuò)誤。

在extern “C”中包含頭文件，可能會(huì)導(dǎo)致被包含頭文件的原有意圖遭到破壞。例如，存在a.h和b.h兩個(gè)頭文件：

使用C++預(yù)處理器展開(kāi)b.h，將會(huì)得到

extern "C"
{
  void foo(int);
  void b();
}

按照a.h作者的本意，函數(shù)foo是一個(gè)C++自由函數(shù)，其鏈接規(guī)范為”C++”。但在b.h中，由于#include “a.h”被放到了extern “C” { }的內(nèi)部，函數(shù)foo的鏈接規(guī)范被不正確地更改了。

示例： 錯(cuò)誤的使用方式：

extern "C"
{
  #include "xxx.h"
  ...
}

正確的使用方式：

#include "xxx.h"

extern "C"
{
  ...
}

建議1.1：一個(gè)模塊通常包含多個(gè).c文件，建議放在同一個(gè)目錄下，目錄名即為模塊名。為方便外部使用者，建議每一個(gè)模塊提供一個(gè).h，文件名為目錄名。

說(shuō)明：需要注意的是，這個(gè).h并不是簡(jiǎn)單的包含所有內(nèi)部的.h，它是為了模塊使用者的方便，對(duì)外整體提供的模塊接口。

以Google test（簡(jiǎn)稱GTest）為例， GTest作為一個(gè)整體對(duì)外提供C++單元測(cè)試框架，其1.5版本的gtest工程下有6個(gè)源文件和12個(gè)頭文件。但是它對(duì)外只提供一個(gè)gtest.h，只要包含gtest.h即可使用GTest提供的所有對(duì)外提供的功能，使用者不必關(guān)系GTest內(nèi)部各個(gè)文件的關(guān)系，即使以后GTest的內(nèi)部實(shí)現(xiàn)改變了，比如把一個(gè)源文件c拆成兩個(gè)源文件，使用者也不必關(guān)心，甚至如果對(duì)外功能不變，連重新編譯都不需要。

對(duì)于有些模塊，其內(nèi)部功能相對(duì)松散，可能并不一定需要提供這個(gè).h，而是直接提供各個(gè)子模塊或者.c的頭文件。

比如產(chǎn)品普遍使用的VOS，作為一個(gè)大模塊，其內(nèi)部有很多子模塊，他們之間的關(guān)系相對(duì)比較松散，就不適合提供一個(gè)vos.h。而VOS的子模塊，如Memory（僅作舉例說(shuō)明，與實(shí)際情況可能有所出入），其內(nèi)部實(shí)現(xiàn)高度內(nèi)聚，雖然其內(nèi)部實(shí)現(xiàn)可能有多個(gè).c和.h，但是對(duì)外只需要提供一個(gè)Memory.h聲明接口。

建議1.2：如果一個(gè)模塊包含多個(gè)子模塊，則建議每一個(gè)子模塊提供一個(gè)對(duì)外的.h，文件名為子模塊名。

說(shuō)明：降低接口使用者的編寫難度。

建議1.3：頭文件不要使用非習(xí)慣用法的擴(kuò)展名，如.inc。

說(shuō)明：目前很多產(chǎn)品中使用了.inc作為頭文件擴(kuò)展名，這不符合c語(yǔ)言的習(xí)慣用法。在使用.inc作為頭文件擴(kuò)展名的產(chǎn)品，習(xí)慣上用于標(biāo)識(shí)此頭文件為私有頭文件。但是從產(chǎn)品的實(shí)際代碼來(lái)看，這一條并沒(méi)有被遵守，一個(gè).inc文件被多個(gè).c包含比比皆是。本規(guī)范不提倡將私有定義單獨(dú)放在頭文件中，具體見(jiàn) 規(guī)則1.1。

除此之外，使用.inc還導(dǎo)致source insight、 Visual stduio等IDE工具無(wú)法識(shí)別其為頭文件，導(dǎo)致很多功能不可用，如“跳轉(zhuǎn)到變量定義處”。雖然可以通過(guò)配置，強(qiáng)迫IDE識(shí)別.inc為頭文件，但是有些軟件無(wú)法配置，如Visual Assist只能識(shí)別.h而無(wú)法通過(guò)配置識(shí)別.inc。

建議1.4：同一產(chǎn)品統(tǒng)一包含頭文件排列方式。

說(shuō)明：常見(jiàn)的包含頭文件排列方式： 功能塊排序、文件名升序、穩(wěn)定度排序。

以穩(wěn)定度排序，建議將不穩(wěn)定的頭文件放在前面，如把產(chǎn)品的頭文件放在平臺(tái)的頭文件前面，如下：

相對(duì)來(lái)說(shuō)， product.h修改的較為頻繁，如果有錯(cuò)誤,不必編譯platform.h就可以發(fā)現(xiàn)product.h的錯(cuò)誤，可以部分減少編譯時(shí)間。

[a1]例如一些屏驅(qū)動(dòng)的地址文件,一些協(xié)議的格式定義文件.只存在.c或者.h即可,不一定兩者都要有.

[a2]我對(duì)自包含沒(méi)有太理解，只是明白在.h文件里盡量不包含沒(méi)有必要的頭文件,某些情況下不得已才進(jìn)行包含其它頭文件的操作.

[a3]這種做法我寫代碼常用,但后面應(yīng)該盡量避免,而是通過(guò)調(diào)用頭文件的方式來(lái)使用該函數(shù).

[a4]對(duì)，我就遇到過(guò)。因?yàn)殡S著工程量的增大，后面某個(gè)細(xì)節(jié)調(diào)整了foo函數(shù),但其它extern調(diào)用它的地方?jīng)]有及時(shí)改正,而KEIL編譯器又沒(méi)有報(bào)錯(cuò),導(dǎo)致bug出現(xiàn),而且不易查找.

往期好文：

C語(yǔ)言、嵌入式重點(diǎn)知識(shí)：回調(diào)函數(shù)

C語(yǔ)言中的goto語(yǔ)句該不該使用？

什么是不完全類型？

我整理了一個(gè)嵌入式資料庫(kù)，大家有什么好資料分享？可以給我留言，我把它加進(jìn)去，資源共享，一起來(lái)完善這個(gè)資料庫(kù)！

（資料庫(kù)鏈接：

https://gitee.com/zhengnianli/EmbedSummary）