折行 Wrapping Lines
每行程式碼最好在 80 個字母以內,且絕不超過 120 字母 一旦超過80個字母,就必需開始考慮折行, 折行的原則如下:- 在逗點之後折行
- 在運算子之後折行 (*、/、%、+、-...)
- 優先於高等級處折行
- 折行後新行開頭對齊前行轉折處等級
| 優 | 差 |
var = a * b / (c - g + f) | var = a * b / |
空白 White Space
縮排符號必需以空白字元表示,而不以Tab表示,建議啟用編輯器將Tab轉換成空白字元的設定. 每個等級的縮排長度為 4 個空白字元. 以空白字元代替Tab的好處如下:- 不因編輯器不同而呈現不同結果
- 有利於折行之後的對齊
二 註解 Comment
- 針對程式碼使用單行註解(',REM, //, #)
- 針對大篇幅的說明段落或文章使用區塊註解(/* ... */)
- 針對類別或函式的開頭說明,使用XML註解
-
C# Java /// <summary> /// This class ... /// </summary> /** <summary> This class... </summary> */
三 宣告 Declarations
每行只有一個宣告 Number of Declarations per Line
好處:- 方便為每個宣告加入註解
- 方便編輯 (刪除或標示為註解)
- 清楚
初始化 Initialization
愈早為變數宣告設定初始值愈好,例如: string name = myObject.Name; 或 int count = 16; 有以下好處:- 增加執行時期的效率
- 避免忘記初始化造成 NullPointerException
除了C, C++, 在C#,VB.Net或Java等種式語言中,儘可能重覆使用變數,例如千萬不要: for (int i = 0 to 100) { BigObject obj = new BigObject();
string name = "Name " + i.ToString(); obj.SetIndex(i) ... } 要改為: BigObject obj = new BigObject();
string name = null; for (int i = 0 to 100) {
name = "Name " + i.ToString(); obj.SetIndex(i); ... } 在.Net中, 多使用using,例如: using (OpenFileDialog openFileDialog = new OpenFileDialog()) { ... }
類別,介面和方法的宣告 Class and Interface Declarations
類別和介面的宣告請遵守以下規範:- 方法名稱與左括弧"("之間不要有空白
- 類別,介面和方法的大括弧"{"和"}"要獨立於一行, 方法或類別內的區塊的左大括弧"{"則要同行,如迴圈,陣列,If或Enum.
- 成對的"{"和"}"要位於相同的縮排位置
- 每個類別,介面和方法的區塊間要間隔一行空白
四 陳述式 Statements
簡單性 Simple Statements
每行只有一個陳述式
If-ElseIf-Else 的格式
- if (condition) { DoSomething(); ... } else if (condition) { DoSomethingOther(); ... } else { DoSomethingOtherAgain(); ... }
- 儘管只有一行的內容,也必需以{ }包裝起來: if (condition) { DoOnlyOneThing(); } 好處在於,除了清楚且不容易出錯,也使後續新增內容時容易維護.
- 如果條件判斷式已經為Boolean型別,則不需再加以判斷其真偽,例如: 要這樣寫: void Increase() { if (isInc) { ++myIndex; } } 而非這樣寫: void Increase() { if (isInc == true) { ++myIndex; } }
For / Foreach Statements
- 基本形式如下: for (int i = 0; i < 5; ++i) { ... } foreach (int i in IntList) { ... }
- 如果只有一行的句子,如下: for (initialization; condition; update); 請考慮用while表示: initialization; while (condition) { update; }
While/Do-While Statements
- 基本形式如下: while (condition) { ... }
- 空的while句子如下: while (condition);
- do-while基本形式如下: do { ... } while (condition);
Switch Statements
- 基本形式如下: switch (condition) { case A: ... break; case B: ... break; default: ... break; }
- 為避免錯誤及增加可讀性,default條件務必放在最後,且要加上break.
五 空白 White Space
空行 Blank Lines
適當的空行可以增加可讀性,使用一個空行的時機如下:- Method or Property 之間
- Class or Interface 之間
- Local variables 的宣告區之後
- Logical sections inside a method.
六 命名規範 Naming Conventions
大小寫風格 Capitalization Styles 介紹
| | Pascal Casing | Camel Casing | Upper Casing |
| 說明 | 每個單字的開頭皆大寫 | 除了第一個單字的開頭小寫,每個單字的開頭皆大寫 | 所有字母皆大寫,單字間以底線"_"區隔 |
| 範例 | PascalCasing | camelCasing | UPPER_CASING |
命名指引 Naming Guidelines
- 不要將型別資訊加入名稱中,例如不要命名 IntegerIndex 或 NameString
- 不要使用匈牙利命名法,除非使用C或C++
- 在Windows介面程式中,請將控制項的完整名稱或適當的簡稱加在變數名稱後方,例如: System.Windows.Forms.Button cancelButton; System.Windows.Forms.Button findBtn; System.Windows.Forms.TextBox nameTextBox;
- 縮寫長度在二個字母以內全部大寫,三個字母以上僅開頭大寫,例如: NationUK, NationUsa, TsmcProject, CAProject, GpgSecurity, HRDepartment
Class Naming Guidelines
- Class名稱應為名詞集合或名詞片語
- 使用 Pascal Casing
- 不要把"Class"加入名稱中
Interface Naming Guidelines
- Interface 名稱應為名詞集合或名詞片語
- 使用 Pascal Casing
- 開頭一律為大寫 I
Enum Naming Guidelines
- 使用 Pascal Casing 在Enum的型別名或內容中
- 內容或型別中不要出現"Enum"
- Enum的型別名表示為單數而非複數
Method Names
- 使用動詞或動詞片語
- .Net 使用 Pascal Casing, Java使用Camel Casing
Property Names
- 使用名詞集合或名詞片語
- 使用 Pascal Casing
Event Names
- 使用sender和e做為EventHandler的參數名
- 使用 Pascal Casing
- Event名稱使用現在進行式或過去式,以清楚表示事件發生的時間點
- 儘可能以動詞命名Event
Capitalization summary
| Type | Case | Notes |
| Class / Struct | Pascal Casing | |
| Interface | Pascal Casing | Starts with I |
| Enum values | Pascal Casing | |
| Enum type | Pascal Casing | |
| Events | Pascal Casing | |
| Exception class | Pascal Casing | End with Exception |
| Public Fields | Pascal Casing | |
| Methods | Pascal Casing | |
| Namespace | Pascal Casing | |
| Property | Pascal Casing | |
| Protected / Private Fields | Camel Casing | |
| Parameters | Camel Casing | |
| Local variables | Camel Casing | |
| Const variables | Upper Casing | |
- 只有在迴圈中才使用i,j,k,m等單一字母的變數,且用途也僅限於計數或索引的功能
七 其它 Others
- 一個函式是否只能有一個返回點? 亦即不可在中途Return 建議: 儘可能如此,但不一定.一切以程式簡單清楚為原則.
-
No 'magic' Numbers
