『壹』 java編程規范！！！
名稱 Java語言編碼規范(Java Code Conventions)
簡介 本文檔講述了Java語言的編碼規范，較之陳世忠先生《c++編碼規范》的浩繁詳盡，此文當屬短小精悍了。而其中所列之各項條款，從編碼風格，到注意事項，不單只Java，對於其他語言，也都很有借鑒意義。因為簡短，所以易記，大家不妨將此作為handbook，常備案頭，逐一對驗。
1 介紹
1.1 為什麼要有編碼規范
1.2 版權聲明
2 文件名
2.1 文件後綴
2.2 常用文件名
3 文件組織
3.1 Java源文件
3.1.1 開頭注釋
3.1.2 包和引入語句
3.1.3 類和介面聲明
4 縮進排版
4.1 行長度
4.2 換行
5 注釋
5.1 實現注釋的格式
5.1.1 塊注釋
5.1.2 單行注釋
5.1.3 尾端注釋
5.1.4 行末注釋
5.2 文擋注釋
6 聲明
6.1 每行聲明變數的數量
6.2 初始化
6.3 布局
6.4 類和介面的聲明
7 語句
7.1 簡單語句
7.2 復合語句
7.3 返回語句
7.4 if，if-else，if else-if else語句
7.5 for語句
7.6 while語句
7.7 do-while語句
7.8 switch語句
7.9 try-catch語句
8 空白
8.1 空行
8.2 空格
9 命名規范
10 編程慣例
10.1 提供對實例以及類變數的訪問控制
10.2 引用類變數和類方法
10.3 常量
10.4 變數賦值
10.5 其它慣例
10.5.1 圓括弧
10.5.2 返回值
10.5.3 條件運算符"?"前的表達式"?"前的表達式
10.5.4 特殊注釋
11 代碼範例
11.1 Java源文件範例
1 介紹(Introction)
1.1 為什麼要有編碼規范(Why Have Code Conventions)
編碼規范對於程序員而言尤為重要，有以下幾個原因：
- 一個軟體的生命周期中，80%的花費在於維護
- 幾乎沒有任何一個軟體，在其整個生命周期中，均由最初的開發人員來維護
- 編碼規范可以改善軟體的可讀性，可以讓程序員盡快而徹底地理解新的代碼
- 如果你將源碼作為產品發布，就需要確任它是否被很好的打包並且清晰無誤，一如你已構建的其它任何產品
為了執行規范，每個軟體開發人員必須一致遵守編碼規范。每個人。
1.2 版權聲明(Acknowledgments)
本文檔反映的是Sun MicroSystems公司，Java語言規范中的編碼標准部分。主要貢獻者包括：Peter King，Patrick Naughton，Mike DeMoney，Jonni Kanerva，Kathy Walrath以及Scott Hommel。
本文檔現由Scott Hommel維護，有關評論意見請發至[email protected]
2 文件名(File Names)
這部分列出了常用的文件名及其後綴。
2.1 文件後綴(File Suffixes)
Java程序使用下列文件後綴：
文件類別 文件後綴
Java源文件 .java
Java位元組碼文件 .class
2.2 常用文件名(Common File Names)
常用的文件名包括：
文件名 用途
GNUmakefile makefiles的首選文件名。我們採用gnumake來創建（build）軟體。
README 概述特定目錄下所含內容的文件的首選文件名
3 文件組織(File Organization)
一個文件由被空行分割而成的段落以及標識每個段落的可選注釋共同組成。超過2000行的程序難以閱讀，應該盡量避免。"Java源文件範例"提供了一個布局合理的Java程序範例。
3.1 Java源文件(Java Source Files)
每個Java源文件都包含一個單一的公共類或介面。若私有類和介面與一個公共類相關聯，可以將它們和公共類放入同一個源文件。公共類必須是這個文件中的第一個類或介面。
Java源文件還遵循以下規則：
- 開頭注釋（參見"開頭注釋"）
- 包和引入語句（參見"包和引入語句"）
- 類和介面聲明（參見"類和介面聲明"）
3.1.1 開頭注釋(Beginning Comments)
所有的源文件都應該在開頭有一個C語言風格的注釋，其中列出類名、版本信息、日期和版權聲明：
/*
* Classname
*
* Version information
*
* Date
*
* Copyright notice
*/
3.1.2 包和引入語句(Package and Import Statements)
在多數Java源文件中，第一個非注釋行是包語句。在它之後可以跟引入語句。例如：
package java.awt;
import java.awt.peer.CanvasPeer;
3.1.3 類和介面聲明(Class and Interface Declarations)
下表描述了類和介面聲明的各個部分以及它們出現的先後次序。參見"Java源文件範例"中一個包含注釋的例子。
類/介面聲明的各部分 註解
1 類/介面文檔注釋(/**……*/) 該注釋中所需包含的信息，參見"文檔注釋"
2 類或介面的聲明
3 類/介面實現的注釋(/*……*/)如果有必要的話 該注釋應包含任何有關整個類或介面的信息，而這些信息又不適合作為類/介面文檔注釋。
4 類的(靜態)變數 首先是類的公共變數，隨後是保護變數，再後是包一級別的變數(沒有訪問修飾符，access modifier)，最後是私有變數。
5 實例變數 首先是公共級別的，隨後是保護級別的，再後是包一級別的(沒有訪問修飾符)，最後是私有級別的。
6 構造器
7 方法 這些方法應該按功能，而非作用域或訪問許可權，分組。例如，一個私有的類方法可以置於兩個公有的實例方法之間。其目的是為了更便於閱讀和理解代碼。
4 縮進排版(Indentation)
4個空格常被作為縮進排版的一個單位。縮進的確切解釋並未詳細指定(空格 vs. 製表符)。一個製表符等於8個空格(而非4個)。
4.1 行長度(Line Length)
盡量避免一行的長度超過80個字元，因為很多終端和工具不能很好處理之。
注意：用於文檔中的例子應該使用更短的行長，長度一般不超過70個字元。
4.2 換行(Wrapping Lines)
當一個表達式無法容納在一行內時，可以依據如下一般規則斷開之：
- 在一個逗號後面斷開
- 在一個操作符前面斷開
- 寧可選擇較高級別(higher-level)的斷開，而非較低級別(lower-level)的斷開
- 新的一行應該與上一行同一級別表達式的開頭處對齊
- 如果以上規則導致你的代碼混亂或者使你的代碼都堆擠在右邊，那就代之以縮進8個空格。
以下是斷開方法調用的一些例子：
someMethod(longExpression1, longExpression2, longExpression3,
longExpression4, longExpression5);
var = someMethod1(longExpression1,
someMethod2(longExpression2,
longExpression3));
以下是兩個斷開算術表達式的例子。前者更好，因為斷開處位於括弧表達式的外邊，這是個較高級別的斷開。
longName1 = longName2 * (longName3 + longName4 - longName5)
+ 4 * longname6; //PREFFER
longName1 = longName2 * (longName3 + longName4
- longName5) + 4 * longname6; //AVOID
以下是兩個縮進方法聲明的例子。前者是常規情形。後者若使用常規的縮進方式將會使第二行和第三行移得很靠右，所以代之以縮進8個空格
//CONVENTIONAL INDENTATION
someMethod(int anArg, Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
...
}
//INDENT 8 SPACES TO AVOID VERY DEEP INDENTS
private static synchronized horkingLongMethodName(int anArg,
Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
...
}
if語句的換行通常使用8個空格的規則，因為常規縮進(4個空格)會使語句體看起來比較費勁。比如：
//DON』T USE THIS INDENTATION
if ((condition1 && condition2)
|| (condition3 && condition4)
||!(condition5 && condition6)) { //BAD WRAPS
doSomethingAboutIt(); //MAKE THIS LINE EASY TO MISS
}
//USE THIS INDENTATION INSTEAD
if ((condition1 && condition2)
|| (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}
//OR USE THIS
if ((condition1 && condition2) || (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}
這里有三種可行的方法用於處理三元運算表達式：
alpha = (aLongBooleanExpression) ? beta : gamma;
alpha = (aLongBooleanExpression) ? beta
: gamma;
alpha = (aLongBooleanExpression)
? beta
: gamma;
5 注釋(Comments)
Java程序有兩類注釋：實現注釋(implementation comments)和文檔注釋(document comments)。實現注釋是那些在C++中見過的，使用/*...*/和//界定的注釋。文檔注釋(被稱為"doc comments")是Java獨有的，並由/**...*/界定。文檔注釋可以通過javadoc工具轉換成HTML文件。
實現注釋用以注釋代碼或者實現細節。文檔注釋從實現自由(implementation-free)的角度描述代碼的規范。它可以被那些手頭沒有源碼的開發人員讀懂。
注釋應被用來給出代碼的總括，並提供代碼自身沒有提供的附加信息。注釋應該僅包含與閱讀和理解程序有關的信息。例如，相應的包如何被建立或位於哪個目錄下之類的信息不應包括在注釋中。
在注釋里，對設計決策中重要的或者不是顯而易見的地方進行說明是可以的，但應避免提供代碼中己清晰表達出來的重復信息。多餘的的注釋很容易過時。通常應避免那些代碼更新就可能過時的注釋。
注意：頻繁的注釋有時反映出代碼的低質量。當你覺得被迫要加註釋的時候，考慮一下重寫代碼使其更清晰。
注釋不應寫在用星號或其他字元畫出來的大框里。注釋不應包括諸如製表符和回退符之類的特殊字元。
5.1 實現注釋的格式(Implementation Comment Formats)
程序可以有4種實現注釋的風格：塊(block)、單行(single-line)、尾端(trailing)和行末(end-of-line)。
5.1.1 塊注釋(Block Comments)
塊注釋通常用於提供對文件，方法，數據結構和演算法的描述。塊注釋被置於每個文件的開始處以及每個方法之前。它們也可以被用於其他地方，比如方法內部。在功能和方法內部的塊注釋應該和它們所描述的代碼具有一樣的縮進格式。
塊注釋之首應該有一個空行，用於把塊注釋和代碼分割開來，比如：
/*
* Here is a block comment.
*/
塊注釋可以以/*-開頭，這樣indent(1)就可以將之識別為一個代碼塊的開始，而不會重排它。
/*-
* Here is a block comment with some very special
* formatting that I want indent(1) to ignore.
*
* one
* two
* three
*/
注意：如果你不使用indent(1)，就不必在代碼中使用/*-，或為他人可能對你的代碼運行indent(1)作讓步。
參見"文檔注釋"
5.1.2 單行注釋(Single-Line Comments)
短注釋可以顯示在一行內，並與其後的代碼具有一樣的縮進層級。如果一個注釋不能在一行內寫完，就該採用塊注釋(參見"塊注釋")。單行注釋之前應該有一個空行。以下是一個Java代碼中單行注釋的例子：
if (condition) {
/* Handle the condition. */
...
}
5.1.3 尾端注釋(Trailing Comments)
極短的注釋可以與它們所要描述的代碼位於同一行，但是應該有足夠的空白來分開代碼和注釋。若有多個短注釋出現於大段代碼中，它們應該具有相同的縮進。
以下是一個Java代碼中尾端注釋的例子：
if (a == 2) {
return TRUE; /* special case */
} else {
return isPrime(a); /* works only for odd a */
}
5.1.4 行末注釋(End-Of-Line Comments)
注釋界定符"//"，可以注釋掉整行或者一行中的一部分。它一般不用於連續多行的注釋文本；然而，它可以用來注釋掉連續多行的代碼段。以下是所有三種風格的例子：
if (foo > 1) {
// Do a double-flip.
...
}
else {
return false; // Explain why here.
}
//if (bar > 1) {
//
// // Do a triple-flip.
// ...
//}
//else {
// return false;
//}
5.2 文檔注釋(Documentation Comments)
注意：此處描述的注釋格式之範例，參見"Java源文件範例"
若想了解更多，參見"How to Write Doc Comments for Javadoc"，其中包含了有關文檔注釋標記的信息(@return, @param, @see)：
http://java.sun.com/javadoc/writingdoccomments/index.html
若想了解更多有關文檔注釋和javadoc的詳細資料，參見javadoc的主頁：
http://java.sun.com/javadoc/index.html
文檔注釋描述Java的類、介面、構造器，方法，以及欄位(field)。每個文檔注釋都會被置於注釋定界符/**...*/之中，一個注釋對應一個類、介面或成員。該注釋應位於聲明之前：
/**
* The Example class provides ...
*/
public class Example { ...
注意頂層(top-level)的類和介面是不縮進的，而其成員是縮進的。描述類和介面的文檔注釋的第一行(/**)不需縮進；隨後的文檔注釋每行都縮進1格(使星號縱向對齊)。成員，包括構造函數在內，其文檔注釋的第一行縮進4格，隨後每行都縮進5格。
若你想給出有關類、介面、變數或方法的信息，而這些信息又不適合寫在文檔中，則可使用實現塊注釋(見5.1.1)或緊跟在聲明後面的單行注釋(見5.1.2)。例如，有關一個類實現的細節，應放入緊跟在類聲明後面的實現塊注釋中，而不是放在文檔注釋中。
文檔注釋不能放在一個方法或構造器的定義塊中，因為Java會將位於文檔注釋之後的第一個聲明與其相關聯。
6 聲明(Declarations)
6.1 每行聲明變數的數量(Number Per Line)
推薦一行一個聲明，因為這樣以利於寫注釋。亦即，
int level; // indentation level
int size; // size of table
要優於，
int level, size;
不要將不同類型變數的聲明放在同一行，例如：
int foo, fooarray[]; //WRONG!
注意：上面的例子中，在類型和標識符之間放了一個空格，另一種被允許的替代方式是使用製表符：
int level; // indentation level
int size; // size of table
Object currentEntry; // currently selected table entry
6.2 初始化(Initialization)
盡量在聲明局部變數的同時初始化。唯一不這么做的理由是變數的初始值依賴於某些先前發生的計算。
6.3 布局(Placement)
只在代碼塊的開始處聲明變數。（一個塊是指任何被包含在大括弧"{"和"}"中間的代碼。）不要在首次用到該變數時才聲明之。這會把注意力不集中的程序員搞糊塗，同時會妨礙代碼在該作用域內的可移植性。
void myMethod() {
int int1 = 0; // beginning of method block
if (condition) {
int int2 = 0; // beginning of "if" block
...
}
}
該規則的一個例外是for循環的索引變數
for (int i = 0; i < maxLoops; i++) { ... }
避免聲明的局部變數覆蓋上一級聲明的變數。例如，不要在內部代碼塊中聲明相同的變數名：
int count;
...
myMethod() {
if (condition) {
int count = 0; // AVOID!
...
}
...
}
6.4 類和介面的聲明(Class and Interface Declarations)
當編寫類和介面是，應該遵守以下格式規則：
- 在方法名與其參數列表之前的左括弧"("間不要有空格
- 左大括弧"{"位於聲明語句同行的末尾
- 右大括弧"}"另起一行，與相應的聲明語句對齊，除非是一個空語句，"}"應緊跟在"{"之後
class Sample extends Object {
int ivar1;
int ivar2;
Sample(int i, int j) {
ivar1 = i;
ivar2 = j;
}
int emptyMethod() {}
...
}
- 方法與方法之間以空行分隔
7 語句(Statements)
7.1 簡單語句(Simple Statements)
每行至多包含一條語句，例如：
argv++; // Correct
argc--; // Correct
argv++; argc--; // AVOID!
7.2 復合語句(Compound Statements)
復合語句是包含在大括弧中的語句序列，形如"{ 語句 }"。例如下面各段。
- 被括其中的語句應該較之復合語句縮進一個層次
- 左大括弧"{"應位於復合語句起始行的行尾；右大括弧"}"應另起一行並與復合語句首行對齊。
- 大括弧可以被用於所有語句，包括單個語句，只要這些語句是諸如if-else或for控制結構的一部分。這樣便於添加語句而無需擔心由於忘了加括弧而引入bug。
7.3 返回語句(return Statements)
一個帶返回值的return語句不使用小括弧"()"，除非它們以某種方式使返回值更為顯見。例如：
return;
return myDisk.size();
return (size ? size : defaultSize);
7.4 if，if-else，if else-if else語句(if, if-else, if else-if else Statements)
if-else語句應該具有如下格式：
if (condition) {
statements;
}
if (condition) {
statements;
} else {
statements;
}
if (condition) {
statements;
} else if (condition) {
statements;
} else{
statements;
}
注意：if語句總是用"{"和"}"括起來，避免使用如下容易引起錯誤的格式：
if (condition) //AVOID! THIS OMITS THE BRACES {}!
statement;
7.5 for語句(for Statements)
一個for語句應該具有如下格式：
for (initialization; condition; update) {
statements;
}
一個空的for語句(所有工作都在初始化，條件判斷，更新子句中完成）應該具有如下格式：
for (initialization; condition; update);
當在for語句的初始化或更新子句中使用逗號時，避免因使用三個以上變數，而導致復雜度提高。若需要，可以在for循環之前(為初始化子句)或for循環末尾(為更新子句)使用單獨的語句。
7.6 while語句(while Statements)
一個while語句應該具有如下格式
while (condition) {
statements;
}
一個空的while語句應該具有如下格式：
while (condition);
7.7 do-while語句(do-while Statements)
一個do-while語句應該具有如下格式：
do {
statements;
} while (condition);
7.8 switch語句(switch Statements)
一個switch語句應該具有如下格式：
switch (condition) {
case ABC:
statements;
/* falls through */
case DEF:
statements;
break;
case XYZ:
statements;
break;
default:
statements;
break;
}
每當一個case順著往下執行時(因為沒有break語句)，通常應在break語句的位置添加註釋。上面的示例代碼中就包含注釋/* falls through */。
7.9 try-catch語句(try-catch Statements)
一個try-catch語句應該具有如下格式：
try {
statements;
} catch (ExceptionClass e) {
statements;
}
一個try-catch語句後面也可能跟著一個finally語句，不論try代碼塊是否順利執行完，它都會被執行。
try {
statements;
} catch (ExceptionClass e) {
statements;
} finally {
statements;
}
8 空白(White Space)
8.1 空行(Blank Lines)
空行將邏輯相關的代碼段分隔開，以提高可讀性。
下列情況應該總是使用兩個空行：
- 一個源文件的兩個片段(section)之間
- 類聲明和介面聲明之間
下列情況應該總是使用一個空行：
- 兩個方法之間
- 方法內的局部變數和方法的第一條語句之間
- 塊注釋（參見"5.1.1"）或單行注釋（參見"5.1.2"）之前
- 一個方法內的兩個邏輯段之間，用以提高可讀性
8.2 空格(Blank Spaces)
下列情況應該使用空格：
- 一個緊跟著括弧的關鍵字應該被空格分開，例如：
while (true) {
...
}
注意：空格不應該置於方法名與其左括弧之間。這將有助於區分關鍵字和方法調用。
- 空白應該位於參數列表中逗號的後面
- 所有的二元運算符，除了"."，應該使用空格將之與操作數分開。一元操作符和操作數之間不因該加空格，比如：負號("-")、自增("++")和自減("--")。例如：
a += c + d;
a = (a + b) / (c * d);
while (d++ = s++) {
n++;
}
printSize("size is " + foo + "\n");
- for語句中的表達式應該被空格分開，例如：
for (expr1; expr2; expr3)
- 強制轉型後應該跟一個空格，例如：
myMethod((byte) aNum, (Object) x);
myMethod((int) (cp + 5), ((int) (i + 3)) + 1);
9 命名規范(Naming Conventions)
命名規范使程序更易讀，從而更易於理解。它們也可以提供一些有關標識符功能的信息，以助於理解代碼，例如，不論它是一個常量，包，還是類。
標識符類型 命名規則 例子
包(Packages) 一個唯一包名的前綴總是全部小寫的ASCII字母並且是一個頂級域名，通常是com，e，gov，mil，net，org，或1981年ISO 3166標准所指定的標識國家的英文雙字元代碼。包名的後續部分根據不同機構各自內部的命名規范而不盡相同。這類命名規范可能以特定目錄名的組成來區分部門(department)，項目(project)，機器(machine)，或注冊名(login names)。 com.sun.eng
com.apple.quicktime.v2
e.cmu.cs.bovik.cheese
類(Classes) 命名規則：類名是個一名詞，採用大小寫混合的方式，每個單詞的首字母大寫。盡量使你的類名簡潔而富於描述。使用完整單詞，避免縮寫詞(除非該縮寫詞被更廣泛使用，像URL，HTML) class Raster;
class ImageSprite;
介面(Interfaces) 命名規則：大小寫規則與類名相似 interface RasterDelegate;
interface Storing;
方法(Methods) 方法名是一個動詞，採用大小寫混合的方式，第一個單詞的首字母小寫，其後單詞的首字母大寫。 run();
runFast();
getBackground();
變數(Variables) 除了變數名外，所有實例，包括類，類常量，均採用大小寫混合的方式，第一個單詞的首字母小寫，其後單詞的首字母大寫。變數名不應以下劃線或美元符號開頭，盡管這在語法上是允許的。
變數名應簡短且富於描述。變數名的選用應該易於記憶，即，能夠指出其用途。盡量避免單個字元的變數名，除非是一次性的臨時變數。臨時變數通常被取名為i，j，k，m和n，它們一般用於整型；c，d，e，它們一般用於字元型。 char c;
int i;
float myWidth;
實例變數(Instance Variables) 大小寫規則和變數名相似，除了前面需要一個下劃線 int _employeeId;
String _name;
Customer _customer;
常量(Constants) 類常量和ANSI常量的聲明，應該全部大寫，單詞間用下劃線隔開。(盡量避免ANSI常量，容易引起錯誤) static final int MIN_WIDTH = 4;
static final int MAX_WIDTH = 999;
static final int GET_THE_CPU = 1;
10 編程慣例(Programming Practices)
10.1 提供對實例以及類變數的訪問控制(Providing Access to Instance and Class Variables)
若沒有足夠理由，不要把實例或類變數聲明為公有。通常，實例變數無需顯式的設置(set)和獲取(gotten)，通常這作為方法調用的邊緣效應 (side effect)而產生。
一個具有公有實例變數的恰當例子，是類僅作為數據結構，沒有行為。亦即，若你要使用一個結構(struct)而非一個類(如果java支持結構的話)，那麼把類的實例變數聲明為公有是合適的。
『貳』 華為編程規范
華為編程規范舉例：
1-1：程序塊要採用縮進風格編寫，縮進的空格數為4個。
說明：對於由開發工具自動生成的代碼可以有不一致。
1-2：相對獨立的程序塊之間、變數說明之後必須加空行。
1-3：較長的語句（>80字元）要分成多行書寫，長表達式要在低優先順序操作符處劃分新行，操作符放在新行之首，劃分出的新行要進行適當的縮進，使排版整齊，語句可讀。
1-4：不允許把多個短語句寫在一行中，即一行只寫一條語句。
1-5：if、for、do、while、case、switch、default等語句自佔一行，且if、for、do、while等語句的執行語句部分無論多少都要加括弧{}。
1-6：對齊只使用空格鍵，不使用TAB鍵。
說明：以免用不同的編輯器閱讀程序時，因TAB鍵所設置的空格數目不同而造成程序布局不整齊，不要使用BC作為編輯器合版本，因為BC會自動將8個空格變為一個TAB鍵，因此使用BC合入的版本大多會將縮進變亂。
1-7：函數或過程的開始、結構的定義及循環、判斷等語句中的代碼都要採用縮進風格，case語句下的情況處理語句也要遵從語句縮進要求。
1-8：程序塊的分界符（如C/C++語言的大括弧『{』和『}』）應各獨佔一行並且位於同一列，同時與引用它們的語句左對齊。在函數體的開始、類的定義、結構的定義、枚舉的定義以及if、for、do、while、switch、case 語句中的程序都要採用如上的縮進方式。
1-9：一行程序以小於80字元為宜，不要寫得過長。
2-1：一般情況下，源程序有效注釋量必須在20％以上。
說明：注釋的原則是有助於對程序的閱讀理解，在該加的地方都加了，注釋不宜太多也不能太少，注釋語言必須准確、易懂、簡潔。
2-2：文件頭部應進行注釋，注釋必須列出：版權說明、版本號、生成日期、作者、內容、功能、修改日誌等。
示例：下面這段頭文件的頭注釋比較標准，當然，並不局限於此格式，但上述信息建議要包含在內。
2-3：函數頭部應進行注釋，列出：函數的目的/功能、輸入參數、輸出參數、返回值、調用關系（函數、表）等。
示例：下面這段函數的注釋比較標准，當然，並不局限於此格式，但上述信息建議要包含在內。
2-4：邊寫代碼邊注釋，修改代碼同時修改相應的注釋，以保證注釋與代碼的一致性。不再有用的注釋要刪除。
2-5：注釋的內容要清楚、明了，含義准確，防止注釋二義性。
說明：錯誤的注釋不但無益反而有害。
2-6：注釋應與其描述的代碼相近，對代碼的注釋應放在其上方或右方（對單條語句的注釋）相鄰位置，不可放在下面，如放於上方則需與其上面的代碼用空行隔開。
2-7：對於所有有物理含義的變數、常量，如果其命名不是充分自注釋的，在聲明時都必須加以注釋，說明其物理含義。變數、常量、宏的注釋應放在其上方相鄰位置或右方。
2-8：數據結構聲明(包括數組、結構、類、枚舉等)，如果其命名不是充分自注釋的，必須加以注釋。對數據結構的注釋應放在其上方相鄰位置，不可放在下面；對結構中的每個域的注釋放在此域的右方。
2-9：全局變數要有較詳細的注釋，包括對其功能、取值范圍、哪些函數或過程存取它以及存取時注意事項等的說明。
2-10：注釋與所描述內容進行同樣的縮排。
說明：可使程序排版整齊，並方便注釋的閱讀與理解。
2-11：避免在一行代碼或表達式的中間插入注釋。
說明：除非必要，不應在代碼或表達中間插入注釋，否則容易使代碼可理解性變差。
2-12：通過對函數或過程、變數、結構等正確的命名以及合理地組織代碼的結構，使代碼成為自注釋的。
說明：清晰准確的函數、變數等的命名，可增加代碼可讀性，並減少不必要的注釋。
2-13：在代碼的功能、意圖層次上進行注釋，提供有用、額外的信息。
說明：注釋的目的是解釋代碼的目的、功能和採用的方法，提供代碼以外的信息，幫助讀者理解代碼，防止沒必要的重復注釋信息。
『叄』 if閫夋嫨緇撴瀯鐨勪功鍐欒勮寖鏈夐偅鍝浜
涓誨皢浠庣幇鍘熷垯if寮曞間粠鍙ワ紝涓誨彞鐢ㄥ皢鏉ユ椂銆
『肆』 c語言代碼編寫的格式
C語言 程序代碼編寫規范
（初級程序員 討論版）
前言
一個好的程序編寫規范是編寫高質量程序的保證。清晰、規范的源程序不僅僅是方便閱讀，更重要的是能夠便於檢查錯誤，提高調試效率，從而最終保證軟體的質量和可維護性。
說明
l 本文檔主要適用於剛剛開始接觸編程的初學者。
l 對於具有一定工程項目開發經驗的程序員，建議學習C語言程序代碼編寫規范—高級版。
目錄
1 代碼書寫規范
2 注釋書寫規范
3 命名規范
4 其它一些小技巧和要求
1 代碼書寫規范
1.1函數定義
花括弧： { }
每個函數的定義和說明應該從第1列開始書寫。函數名（包括參數表）和函數體的花括弧應該各佔一行。在函數體結尾的括弧後面可以加上注釋，注釋中應該包括函數名，這樣比較方便進行括弧配對檢查，也可以清晰地看出來函數是否結束。
範例1：函數的聲明
void matMyFunction(int n)
{
……
} /* matMyFunction*/
1.2空格與空行的使用
要加空格的場合
l 在逗號後面和語句中間的分號後面加空格，如：
int i, j, k;
for (i = 0; i < n; i++)
result = func(a, b, c);
l 在二目運算符的兩邊各留一個空格，如
a > b a <= b i = 0
l 關鍵字兩側，如if () …, 不要寫成if() …
l 類型與指針說明符之間一定要加空格：
char *szName;
不加空格的場合
l 在結構成員引用符號.和->左右兩加不加空格：
pStud->szName, Student.nID
l 不在行尾添加空格或Tab
l 函數名與左括弧之間不加空格:
func(…)
l 指針說明符號*與變數名間不要加空格:
int *pInt; 不要寫成: int * pInt;
l 復合運算符中間不能加空格，否則會產生語法錯誤，如：
a + = b a < = b 都是錯誤的
空行與換行
l 函數的變數說明與執行語句之間加上空行;
l 每個函數內的主要功能塊之間加空行表示區隔;
l 不要在一行中寫多條語句.
範例2：空行與換行
int main()
{
int i, j, nSum = 0; //變數說明
for (i = 0; i < 10; i++) //執行代碼
{
for (j = 0; j < 10; j++)
{
nSum += i;
}
}
}
1.3縮進的設置
根據語句間的層次關系採用縮進格式書寫程序，每進一層，往後縮進一層
有兩種縮進方式：1，使用Tab鍵；2，採用4個空格。
整個文件內部應該統一，不要混用Tab鍵和4個空格，因為不同的編輯器對Tab鍵的處理方法不同。
1.4折行的使用
· 每行的長度不要超過80個字元，當程序行太長時，應該分行書寫。
· 當需要把一個程序行的內容分成幾行寫時，操作符號應該放在行末。
· 分行時應該按照自然的邏輯關系進行，例如：不要把一個簡單的邏輯判斷寫在兩行上。
· 分行後的縮進應該按照程序的邏輯關系進行對齊。例如：參數表折行後，下面的行應該在參數表左括弧的下方。
範例2：折行的格式
dwNewShape = matAffineTransform(coords, translation,
rotation);
if (((new_shape.x > left_border) &&
(new_shape.x < right_border)) &&
((new_shape.y > bottom_border) &&
(new_shape.y < top_border)))
{
draw(new_shape);
}
1.5嵌套語句（語句塊）的格式
對於嵌套式的語句--即語句塊（如，if、while、for、switch等）應該包括在花括弧中。花括弧的左括弧應該單獨佔一行，並與關鍵字對齊。建議即使語句塊中只有一條語句，也應該使用花括弧包括，這樣可以使程序結構更清晰，也可以避免出錯。建議對比較長的塊，在末尾的花括弧後加上注釋以表明該語言塊結束。
範例3：嵌套語句格式
if (value < max)
{
if (value != 0)
{
func(value);
}
}
} else {
error("The value is too big.");
} /* if (value < max) */
2 注釋書寫規范
注釋必須做到清晰，准確地描述內容。對於程序中復雜的部分必須有注釋加以說明。注釋量要適中，過多或過少都易導致閱讀困難。
2.1注釋風格
· C語言中使用一組（/* … */）作為注釋界定符。
· 注釋內容盡量用英語方式表述。
· 注釋的基本樣式參考範例4。
· 注釋應該出現在要說明的內容之前，而不應該出現在其後。
· 除了說明變數的用途和語言塊末尾使用的注釋，盡量不使用行末的注釋方式。
範例4：幾種注釋樣式
/*
* ************************************************
* 強調注釋
* ************************************************
*/
/*
* 塊注釋
*/
/* 單行注釋 */
//單行注釋
int i; /*行末注釋*/
2.2何時需要注釋
· 如果變數的名字不能完全說明其用途，應該使用注釋加以說明。
· 如果為了提高性能而使某些代碼變得難懂，應該使用注釋加以說明。
· 對於一個比較長的程序段落，應該加註釋予以說明。如果設計文檔中有流程圖，則程序中對應的位置應該加註釋予以說明。
· 如果程序中使用了某個復雜的演算法，建議註明其出處。
· 如果在調試中發現某段落容易出現錯誤，應該註明。
3 命名規范
3.1常量、變數命名
l 符號常量的命名用大寫字母表示。如：
#define LENGTH 10
l 如果符號常量由多個單詞構成，兩個不同的單詞之間可以用下劃線連接。如：
#define MAX_LEN 50
變數命名的基本原則：
l 可以選擇有意義的英文（小寫字母）組成變數名，使人看到該變數就能大致清楚其含義。
l 不要使用人名、地名和漢語拼音。
l 如果使用縮寫，應該使用那些約定俗成的，而不是自己編造的。
l 多個單片語成的變數名，除第一個單詞外的其他單詞首字母應該大寫。如：
dwUserInputValue。
3.2函數命名
函數命名原則與變數命名原則基本相同。對於初學者，函數命名可以採用「FunctionName」的形式。
4 其它一些小技巧和要求
l 函數一般情況下應該少於100行
l 函數定義一定要包含返回類型，沒有返回類型加void
l 寫比較表達式時，將常量放在左邊
10 == n
NULL != pInt
l 指針變數總是要初始或重置為NULL
l 使用{}包含復合語句，即使是只有一行，如：
if (1 == a)
{
x = 5;
}
http://home.ustc.e.cn/~danewang/c/CodingStandards.html