一站式示例代碼編程規(guī)范

本文檔描述了微軟一站式代碼示例庫項目組所采納的關于本地

C++和.NET(C#和VB.NET)代碼的編程風格指導規(guī)范。

鳴謝

本文檔的每一章節(jié)都應該感謝DanRuder-微軟PrincipalEscalationEngineer。Dan對本文檔進行了斟字酌

句的查閱，并根據(jù)其20余年的編程經(jīng)驗提供了大量的珍貴評論。我很榮幸能與他共事。

我同樣感謝微軟的四位經(jīng)理，感謝他們對該項目的一貫支持。他們是VivianLuo,AllenDing,FelixWu和

MeiLiango

同時，如果沒有如下一站式代碼示例庫項目的關鍵成員的辛勤付出，本文檔必定不會具有現(xiàn)在的技術深

度以及完整度，我在這里要感謝他們：

HongyeSunJieWangJiZhouMichaelSunKiraQianLindaLiu

AllenChenYi-LunLuoStevenChengWen-JunZhang

本文檔部分章節(jié)參考自一些微軟產(chǎn)品組的編程規(guī)范。感謝他們的慷慨共享。

本編程規(guī)范在不斷改善。如果您發(fā)現(xiàn)某些最佳實踐或者話題并沒有涵蓋在本文檔中，請告知我們一站式

示例代碼庫項目組，以不斷充實改善本文檔。我期待著您的參與。?

聲明

本編程規(guī)范文檔以“如是”提供，無論明示或喑示都不包含任何形式保證，但并不限制適用于特殊目的

的默認擔保。

當您編寫VC++/VC#/VB.NET代碼時，敬請參考或使用本文檔。但是，我們希望您能通過

onecode@告知我們您正在使用本文檔，或給出任何改進建議。

目錄

1概覽1

1.1原則和主旨1

1.2術語2

2通用編程規(guī)范3

2.1明確和一致3

2.2格式和風格3

2.3庫的使用4

2.4全局變量4

2.5變量的聲明和初始化5

2.6函數(shù)的聲明和調用5

2.7語句6

2.8枚舉7

2.9空格10

2.10大括號11

2.11注釋11

2.12代ii馬塊18

3C++編程規(guī)范19

3.1編譯器選項19

3.2文件和結構20

3.3命名規(guī)范21

3.4指針23

3.5常量23

3.6類型轉換24

3.7Sizeof24

3.8字符串25

3.9數(shù)組26

3.10宏26

3.11函數(shù)27

3.12結構體29

3.13類錯誤！未定義書簽。

3.14COM34

3.15動態(tài)分配35

3.16錯誤和異常35

3.17資源清理37

3.18控制流38

4.NET編碼規(guī)范41

4.1類庫開發(fā)設計規(guī)范41

4.2文件和結構41

4.3程序集屬性41

4.4命名規(guī)范41

4.5常量43

4.6字符串43

4.7數(shù)組和集合44

4.8結構體46

4.9類47

4.10命名空間50

4.11錯誤和異常50

4.12資源清理52

4.13交互操作61

Page1

2.正確性-示例代碼必須正確展示出其欲告

1概覽

知使用者的重點。代碼必須經(jīng)過測試，且

可以按照文檔描述進行編譯和運行。

木文檔為一站式示例代碼庫項目組所使用的C++

以及.NET編碼規(guī)范。該規(guī)范源自于產(chǎn)品開發(fā)過程

3.一致性-示例代碼應該按照一致的編程風

中的經(jīng)驗，并在不斷完善。如果您發(fā)現(xiàn)一些最佳

格和設計來保證代碼易讀。同樣的，不同

實踐或者話題并沒有涵蓋在本文檔中，請聯(lián)系我

代碼示例之間也應當保持一致的風格和設

們一站式示例代碼庫項目組，以不斷充實完善本

計，使使用者能夠很輕松的結合使用它

文檔。

們。一致性將我們一站式示例代碼庫優(yōu)良

的品質形象傳遞給使用者，展示出我們對

任何指導準則都可能會眾口難調。本規(guī)范的目的

于細節(jié)的追求。

在于幫助社區(qū)開發(fā)者提高開發(fā)效率，減少代碼中

可能出現(xiàn)的bug,并增強代碼的可維護性。萬事開

4.流行性-代碼示例應當展示現(xiàn)行的編程實

頭難，采納一個不熟悉的規(guī)范可能在初期會有一

踐，例如使用Unicode,錯誤處理，防御式

些棘手和困擾，但是這些不適應很快便會消失，

編程以及可移植性。示例代碼應當使用當

它所帶來的好處和優(yōu)勢很快便會顯現(xiàn)，特別是在

前推薦的運行時庫和API函數(shù)，以及推薦

當您接手他人代碼時。

的項目和生成設置。

1.1原則和主旨

5.可靠性-代碼示例必須符合法律，隱私和

高質量的代碼示例往往具有如下特質：

政策標準和規(guī)范。不允許展示入侵性或低

質的編程實踐，不允許永久改變機器狀

1.易懂-代碼示例必須易讀且簡單明確。它

們必須能展示出重點所在。示例代碼的相態(tài)。所有的安裝和執(zhí)行過程必須可以被撤

關部分應當易于重用。示例代碼不可包含銷。

多余代碼。它們必須帶有相應文檔說明。

6.安全性-示例代碼應該展示如何使用安全

的編程實踐：例如最低權限原則，使用運

?2013MicrosoftCorporation.Allrightsreserved.All-In-OneCodeFramework()

Page2

行時庫函數(shù)的安全版本，以及SDL推薦的

項目設置。

合理使用編程實踐，設計和語言特性決定了示例

代碼是否可以很好滿足上述特性。本編程規(guī)范致

力于幫助您創(chuàng)建代碼示例以使使用者能夠作為最

佳實踐來效仿和學習。

1.2術語

在整個文檔中，會有一些對于標準和實踐的推薦

和建議。?些實踐是非常重要的，必須嚴格執(zhí)

行，另一些指導準則并不一定處處適用，但是會

在特定的場景下帶來益處。為了清楚陳述規(guī)范和

實踐的意圖，我們會使用如下術語。

術語意圖1理由

13一定請…該規(guī)范或實踐在任何情況卜都應該遵守。如果您認為您的應用是例

夕卜，則可能不適用。該規(guī)范用于減少bug.

0一定不要…不允許應用該規(guī)范或實踐。

0您應該…該規(guī)范和實踐適用于大多數(shù)情況。該規(guī)范用于統(tǒng)一編程風格，保持一致和清

晰的風格。

S您不應該??不應該應用該規(guī)范或實踐，除非有合理的理由。

團您可以…該標準和規(guī)范您可以按需應用。該規(guī)范可用于編程風格，但不總是有益

的。

?2013MicrosoftCorporation.Allrightsreserved.All-In-OneCodeFramework()

Page3

Options

FileExtensionIndenting

2通用編程規(guī)范AllLanguages?None

>BasicBlock

03

oSmart

,C/C++

General

這些通用編程規(guī)范適用于所有語言-它們對代碼Tab

Tabs

Tabsize4

Formatting

風格，格式和結構提供了全局通用的指導。>CSS

Indentsize:4

t>HTML

>JScript@Insertspaces

t>PL/SQL

2.1明確性和一致性>PlainTextKeeptabs

SQLScript

t>T-SQL

國一定請確保代碼的明確性，易讀性和透明性。>T-SQL7

t>T-SQL80

T-SQL90

編程規(guī)范致力于確保代碼是易懂和易維護的。沒「?XAML

有什么勝于清晰、簡潔、自描述的代碼。

回一定請確保一旦應用了某編程規(guī)范，需在所有

0您應該限制一行代碼的最大長度。過長的代碼

代碼中應用，以保持一致性。

降低了代碼易讀性。為了提高易讀性，招代碼長

2.2格式和風格度設置為78列。若78列太窄，可以設置為86或

岡一定不要使用制表符。不同的文字編輯器使用者90o

不同的空格來生成制表符，這就帶來了格式混

VisualC++sample:

亂。所有代碼都應該使用4個空格來表示縮進。

//Getanddisplaywhethertheprimaryaccesstokenof

//belongstouseraccountthatisamemberoftheloca

//groupevenifitcurrentlyisnotelevated(IsUserln

可以配置VisualStudio文字編輯器，以空格代替制HWNDhlnAdminGroupLabel=GetDlgItem(hWnd,IDC-INADMING

try

表符。(

BOOLconstflnAdminGroup=IsUserlnAdminGroupO;

SetWindowText(hlnAdminGroupLabel,flnAdminGroup?L

)

catch(DWORDdwError)

(

SetWindowText(hlnAdminGroupLabel,LMN/A0);

wn

ReportError(LIsUserInAdminGrouprdwError);

)

VisualC#示例:

?2013MicrosoftCorporation.Allrightsreserved.All-In-OneCodeFramework()

Page4

//GetanddisplaywhethertheprimaryaccesstOptions

//touseraccountthatisamemberoftheloca

Showsettingsfor:

//ifitcurrentlyisnotelevated(IsUserlnAdn/Environment

General|TextEditor

try

Add-in/MacrosSecurity

{AutoRecoverFont(boldtypeindicatesfixed-widthfonts):

boolflnAdminGroup=IsUserlnAdminGroupO;DocumentsCourierNew

this.IblnAdminGroup.Text=flnAdminGroup.ToFindandReplace

}FontsandColorsDisplayitemsH

catch(Exceptionex)HelpPlainText

ImportandExportSettingsSelectedText

(InternationalSettingsInactiveSelectedText

WW

this.IblnAdminGroup.Text=N/A;KeyboardIndicatorMargin

LineNumbers

MessageBox.Show(ex.Message,"AnerroroccurStartup

VisibleWhiteSpace

MessageBoxButtons.OK,MesaageBoxIcon.ErTaskListBookmark

}WebBrowserBraceMatching(Highlight)

PerformanceToolsBraceMatching(Rectangle)

?ProjectsandSolutionsBreakpoint(Disabled)

Breakpoint(Enabled)

t>SourceControl

VisualBasicsample:Breakpoint(Error)

■TextEditor

General

,Getanddisplaywhethertheprimaryaccesstc

'touseraccountthatisamemberofthelocal

,ifitcurrentlyisnotelevated(IsUserlnAdmi

Try

DimflnAdminGroupAsBoolean=Me.IsUserlnAdminGroup

Me.IblnAdminGroup.TextfInAdminGroup.Tos皆守庫的使用

CatchexAsException

Me.IblnAdminGroup.Text="N/A”

MessageBox.Show(ex.Message,"Anerroroccur跟丁定基引用必甄的瓶，，包括不必要的頭文

MessageBoxButtons,OK,MessageBoxIcon.Error)

EndTry件，或引用不必要的程序集。注重細節(jié)能夠減少

項目生成時間，最小化出錯幾率，并給讀者一個

國一定請在您的代碼編輯器中使用定寬字體，例

良好的印象。

如CourierNew。

2.4全局變量

0一定請盡量少用全局變量。為了正確的使用全

局變量，一般是將它們作為參數(shù)傳入函數(shù)。永遠

不要在函數(shù)或類內部直接引用全局變量，因為這

會引起一個副作用：在調用者不知情的情況下改

變了全局變量的狀態(tài)。這對于靜態(tài)變量同樣適

用。如果您需要修改全局變量，您應該將其作為

-一個輸出參數(shù)，或返回其一份全局變量的拷貝。

?2013MicrosoftCorporation.Allrightsreserved.All-In-OneCodeFramework()

Page5

2.5變量的聲明和初始化

Bad:

CodeExample*pFirst,*pSecond；

因一定請在最小的，包含該局部變量的作用域塊

內聲明它。一般，如果語言允許，就僅在使用前后一個代碼示例經(jīng)常被誤寫為：

CodeExample*pFirstpSecond；

聲明它們，否則就在作用域塊的頂端聲明。z

這種誤寫實際上等同于：

0一定請在聲明變量時初始化它們。

CodeExample*pFirst；

CodeExamplepSecond；

因一定請在語言允許的情況下，將局部變量的聲

明和初始化或賦值置于同一行代碼內。這減少了2.6函數(shù)的聲明和調用

代碼的垂直空間，確保了變量不會處在未初始化函數(shù)或方法的名稱，返回值，參數(shù)列表可以有多

的狀態(tài)。種形式。原則上應該都將這些置于同一行代碼

內。如果帶有過多參數(shù)不能置于一行代碼，可以

//C++sample：

HANDLEhToken=NULL;

進行換行：多個參數(shù)一行或者一個參數(shù)一行。將

PSIDplntegritySid=NULL；

STARTUPINFOsi={sizeof(si)}；返回值置于函數(shù)或方法名稱的同一行。例如，

PROCESS_INFORMATIONpi={0};

//C#sample：

單行格式：

stringname=myObject.Name；

intval=time.Hours；

//C++functiondeclarationsample：

?VB.NETsample：HRESULTDoSomeFunctionCa11(intparaml

DimnameAsString=myObject.Nameintparam2,int*param3)；

DimvalAsInteger=time.Hours//C++/C#functioncallsample：

hr=DoSomeFunctionCall(paraml,

param2,param3)；

B一定不要在同一行中聲明多個變量。推薦每行'VB.NETfunctioncallsample：

hr=DoSomeFunctionCall(paraml

只包含一句聲明，這樣有利于添加注釋，也減少z

param2,param3)

歧義。例如VisualC++示例，

多行格式：

Good:

CodeExample*pFirst=NULL；////C++functiondeclarationsample：

Pointerofthefirstelement.HRESULTDoSomeFunctionCall(intparaml

CodeExample*pSecond=NULL；//intparam2,int*param3z

Pparam4zintparamS);

?2013MicrosoftCorporation.Allrightsreserved.All-In-OneCodeFramework()

Page6

//C++/C#functioncallsample：paramS)

hr=DoSomeFunctionCall(paramlz

param2,param3,

團一定請將參數(shù)排序，并首先將輸入?yún)?shù)分組，

param4,param5)；

'VB.NETfunctioncallsample：

再將輸出參數(shù)放置最后。在參數(shù)組內，按照能夠

hr=DoSomeFunctionCa11(paraml,

param2,param3,_

幫助程序員輸入正確值的原則來將參數(shù)排序。比

param4zparamS)

如，如果一個函數(shù)帶有2個參數(shù)，"left"和

將參數(shù)列表置于多行代碼時，每個參數(shù)應該整

“right",將"left"置于"right"之前，則它們的放置

齊排列于前一個參數(shù)的下方。第一個類型/參數(shù)對

順序符合其參數(shù)名。當設計一系列具有相同參數(shù)

置于新行行首，并縮進一個制表符寬度。函數(shù)或

的函數(shù)時，在各函數(shù)內使用一致的順序。比如，

方法調用時的參數(shù)列表同樣需按照這一格式。

如果一個函數(shù)帶有一個輸入類型為句柄的參數(shù)作

//C++sample：

為第一參數(shù)，那么所有相關函數(shù)都應該將該輸入

HRESULTDoSomeFunctionCall(

HWNDhwnd,//Youcancomment

句柄作為第一參數(shù)。

parameters,too

T1paraml,//Indicates

something

2.7代碼語句

T2param2z//Indicates

somethingelse

0一定不要在同一行內放置一句以上的代碼語

T3param3,//Indicatesmore

T4param4,//Indicateseven

句。這會使得調試器的單步調試變得更為困難。

more

T5param5)；//Yougettheidea

Good:

//C++/C#sample//C++/C#sample：

hr=DoSomeFunctionCall(a=1；

b=2;

hwndz

paraml,

param2,'VB.NETsample：

param3,If(IsAdministrator())Then

param4,Console.WriteLine("YES")

param5)；EndIf

*VB.NETsample：Bad:

hr=DoSomeFunctionCall(//C++/C#sample：

hwnd,_a=1；b=2;

paraml,_

param2,_'VB.NETsample：

param3,_If(IsAdministrator())Then

param4,_Console.WriteLine("YES")

?2013MicrosoftCorporation.Allrightsreserved.All-In-OneCodeFramework()

Page7

枚舉

2.8#defineRED0

#defineGREEN1

因一定請將代表某些值集合的強類型參數(shù)，屬性

#defineBLUE2

和返回值聲明為枚舉類型。

//C#sample：

publicstaticclassColor

一定請在合適的情況下盡量使用枚舉類型，而

13publicconstintRed=0；

publicconstintGreen=1

不是靜態(tài)常量或值。枚舉類型是一個具

"#define"publicconstintBlue=2；

)

有一個靜態(tài)常量集合的結構體。如果遵守這些規(guī)

'VB.NETsample：

范，定義枚舉類型，而不是帶有靜態(tài)常量的結構

PublicClassColor

PublicConstRedAsInteger=0

體，您便會得到額外的編譯器和反射支持。

PublicConstGreenAsInteger=1

PublicConstBlueAsInteger=2

Good:EndClass

//C++sample：

enumColor

因一定不要使用公開集合作為枚舉(例如操作系

(

Red,

統(tǒng)版本，您親朋的姓名)。

Green,

Blue

};

團一定請為簡單枚舉提供一個。值枚舉量，可以

//C#sample：

考慮將之命名為。如果這個名稱對于特定

publicenumColor"None"

(

的枚舉并不合適，可以自行定義為更準確的名

Red,

Green,

稱。

Blue

)

//C++sample：

'VB.NETsample：enumCompression

PublicEnumColor(

RedNone=0,

GreenGZip,

BlueDeflate

EndEnum);

Bad://C#sample：

//C++sample：publicenumCompression

constintRED=0；{

constintGREEN=1;None=0,

constintBLUE=2；GZip,

?2013MicrosoftCorporation.Allrightsreserved.All-In-OneCodeFramework()

Page8

DeflateThrowNew

)ArgumentOutOfRangeException(...)；

EndIf

'VB.NETsample：

PublicEnumCompression

2.8.1標志枚舉

None=0

GZip

Deflate標志枚舉用于對枚舉值進行位運算的支持。標志

EndEnum

枚舉通常用于表示選項。

S一定不要在.NET中使用Enum.lsDefined來檢查

0一定要將System.FlagsAttribute應用于標志枚

枚舉范圍。Enum.lsDefined有2個問題。首先，它

舉。一定不要將此屬性用于簡單枚舉。

加載反射利大量類型元數(shù)據(jù)，代價極其昂貴。第

二，它存在版本的問題。

0一定請利用2進制強大的能力，因為它可以自

Good:由的進行位異或運算。舉例，

//C#sample：

if(c>Color.Black||c<