前言

總結(jié)軟件工程中的一些通用編碼規(guī)范。

提示：以下內(nèi)容參考chat回答

一、通用編碼規(guī)范

1. 命名規(guī)范

• 變量、函數(shù)、類和文件名應(yīng)該簡明易懂，使用英文單詞或單詞縮寫，并使用下劃線或駝峰命名法。
• 變量名應(yīng)該使用名詞，函數(shù)名應(yīng)該使用動詞，類名應(yīng)該使用名詞或名詞短語，文件名應(yīng)該使用有意義的名稱。
• 舉例：

first_name = "John"
last_name = "Doe"

（1）使用駝峰命名法

def calculateSalary():
    pass
    
class CustomerOrder:
    pass

（2）使用有意義的文件名

customer_order.py

2. 格式化規(guī)范

• 代碼行長度應(yīng)該不超過80個字符。
• 使用一致的縮進(jìn)和空格以使代碼更易于閱讀
• 在兩個操作符之間使用空格，例如賦值、比較和算術(shù)操作符
• 舉例：
  （1）代碼行長度不超過80個字符

def calculate_discount(price, discount_percentage):
    return price * discount_percentage / 100

（2）使用一致的縮進(jìn)和空格

if user_age < 18:
    print("You are a minor")
else:
    print("You are an adult")

（3）在賦值、比較和算術(shù)操作符之間使用空格

age = 25
if age == 18:
    print("You are a young adult")

3. 注釋規(guī)范

• 注釋應(yīng)該清晰、有意義，并解釋代碼的目的，而不是顯而易見的東西。
• 注釋應(yīng)該寫在需要注釋的代碼上面，并在需要的地方使用空行分隔。
• 舉例：

def calculate_discount(price, discount_percentage):

（1）計算折扣后的價格

return price * discount_percentage / 100

（2）兩行空行分隔

class CustomerOrder:

4. 函數(shù)的長度規(guī)范

• 盡量保持函數(shù)的短小精悍，以提高代碼的可讀性和可維護(hù)性。
• 函數(shù)應(yīng)該只做一件明確的事情，如果函數(shù)過于復(fù)雜，則需要將其拆分成較小的函數(shù)。
• 舉例：

def process_customer_order(customer, order_items):

（1）檢查客戶地址的有效性

 check_address(customer.address)

（2）檢查訂單是否有足夠的庫存

for item in order_items:
    check_stock(item.product_code, item.quantity)

（3）保存訂單

 save_order(customer, order_items)

（4）較短函數(shù)

def check_address(address):

（5）檢查地址的有效性

def check_stock(product_code, quantity):

（6）檢查庫存是否充足

    pass

def save_order(customer, order_items):

（7） 保存訂單

5. 錯誤處理規(guī)范

• 帶有適當(dāng)錯誤處理的代碼不僅更可靠，而且更容易調(diào)試。
• 盡可能使用異常處理來處理錯誤。
• 舉例：

（1）試圖打開一個不存在的文件

try with open("non_existing_file.txt", "r") as f:
    content = f.read()

（2）捕獲文件不存在的異常

except FileNotFoundError:
    print("File not found")

6. 冗余代碼規(guī)范

• 盡管DRY（不要重復(fù)自己）原則已經(jīng)很出名了，但它仍然是一個很好的編程實踐，可以減少冗余代碼和錯誤數(shù)量。
• 盡可能使用現(xiàn)有的代碼或函數(shù)，而不是編寫新的代碼。
• 舉例：

if user_age < 18:
    print("You are a minor")
else:
    print("You are an adult")

不需要重復(fù)代碼

if is_minor(user_age):
    print("You are a minor")
else:
    print("You are an adult")

可以使用函數(shù)

def is_minor(age):
    return age < 18

7. 通用開發(fā)模式規(guī)范

• 在編程實踐中盡量使用通用的設(shè)計模式，以提高代碼的可維護(hù)性。
• 使用面向?qū)ο缶幊痰脑瓌t如高內(nèi)聚、低耦合等。
• 舉例：

class Customer:
    def __init__(self, name, email, phone):
        self.name = name
        self.email = email
        self.phone = phone

class Order:
    def __init__(self, customer, items):
        self.customer = customer
        self.items = items

二、逸哥總結(jié)的編碼規(guī)范

以下編碼規(guī)范來自于大佬張逸的文檔資料。

1.前言

1.1編寫目的

為了保證編寫出的程序都符合相同的規(guī)范，保證一致性、統(tǒng)一性而建立的程序編碼規(guī)范。

編碼規(guī)范對于程序員而言尤為重要，有以下幾個原因：

1. 一個軟件的生命周期中，80%的花費在于維護(hù)。
2. 幾乎沒有任何一個軟件，在其整個生命周期中，均由最初的開發(fā)人員來維護(hù)。
3. 編碼規(guī)范可以改善軟件的可讀性，可以讓程序員盡快而徹底地理解新的代碼 。
   每個軟件開發(fā)人員都必須遵守統(tǒng)一的編碼規(guī)范。

1.2適用范圍

本規(guī)范適用于《從零開始編寫自己的C# 框架》的開發(fā)。

1.3基本要求

盡量使代碼簡單直白。

2.命名規(guī)范

2.1字母大小寫約定

2.1.1說明
表達(dá)清晰的命名規(guī)范是程序規(guī)劃的核心，如果規(guī)范的命名能清晰的表達(dá)出相應(yīng)的功能，就可以讓人“望文知意”，提高開發(fā)效率和系統(tǒng)的可維護(hù)性。反之，如果命名不能表達(dá)其含義，例如“aaa”、“bbb ()”，那么將適得其反。
2.1.2Pascal風(fēng)格
包含一到多個單詞，每一個單詞第一個字母大寫，其余字母均小寫。例如：HelloWorld、SetName等。
2.1.3Camel風(fēng)格
包含一到多個單詞，第一個單詞首字母小寫，其余單詞首字母大寫。例如：name、productId等。

2.2標(biāo)識符的大小寫規(guī)則

（1）除了參數(shù)與變量外，所有命名空間名稱、類、函數(shù)、接口、屬性等名稱的命名，使用 Pascal 風(fēng)格。
（2）參數(shù)與變量的命名，使用Camel風(fēng)格。

2.3通用命名約定

約定的是如何選擇最適當(dāng)?shù)拿Q，這些準(zhǔn)則適用于所有標(biāo)識符命名。

2.3.1選擇名稱

(1)請選擇易讀的英文名稱
例如，英文 Order的意思為規(guī)則、次序、訂購等，如果用在排序列中就不是很合適，用來表示訂單則更具可讀性。
可讀性比詳細(xì)描述更重要，比如表示坐標(biāo)名稱ScreenX就比ScreenHorizontally 更具可讀性。

(2)除下劃線外，不要使用連字符或任何其他非字母數(shù)字字符
在數(shù)據(jù)庫表字段名稱設(shè)計時，與其他表字段有關(guān)聯(lián)時，適當(dāng)?shù)氖褂帽砻?下橫線+字段名，可以更清晰的表現(xiàn)出該字段與關(guān)聯(lián)表對應(yīng)字段的關(guān)系。
比如產(chǎn)品分類表ProductClass有字段Id與Name，那么產(chǎn)品表綁定這兩個字段的名稱可命名為ProductClass_Id與ProductClass_Name，這樣在查看產(chǎn)品表時就可以清晰的知道這兩個字段與分類表的關(guān)系。

(3)避免使用與常用編程語言的關(guān)鍵字沖突的標(biāo)識符

(4)變量和方法參數(shù)使用Camel 風(fēng)格
例如：

string productName = "";
int number=0;
string sqlString="";
double averageScore=0.0;
Users users=new Users();
Users model=new Users();
Users userModel=new Users();
const string const_String = "";（不同公司有不同的約定，具體根據(jù)自己公司情況設(shè)置而定）

	Private string GetProductName(int id)
{
		return "";
}

(5)不要使用成員屬性作為成員變量的前綴（其他變量命名也一樣）
例如： 不要像Users m_users;這樣定義成員變量，可以使用第4點的設(shè)置。

2.3.2字母縮寫詞

(1)通常，不應(yīng)使用縮寫

(2)除非這種縮寫已廣泛接受，又或者團隊當(dāng)中大家都認(rèn)可一種縮寫
例如，使用 OnButtonClick，如果團隊中普遍認(rèn)可OnBtnClick這種寫法也是可以的。

2.4命名空間命名

命名空間命名采用Pascal風(fēng)格，取名的一般規(guī)則如下。
CompanyName. ProjectName （公司名稱.項目名稱）
例如：

Microsoft.Office

需要用復(fù)數(shù)時，請使用復(fù)數(shù)。
例如，使用System.Collections而不是System.Collection。
需要縮寫時，不需要加復(fù)數(shù)。
例如：使用System.IO而不是System.IOs。

2.5類、結(jié)構(gòu)和接口命名

(1)按照 Pascal 大小寫格式，使用名詞或名詞短語為類、接口和值類型命名

(2)接口命名以字母 I 為前綴
例如：IComponent

(3)派生類的末尾使用基類名稱
例如，從 Stream 繼承的 Framework 類型以 Stream 結(jié)尾，從 Exception 繼承的類型以 Exception 結(jié)尾。

2.6邏輯層類命名

按照 Pascal 大小寫格式，使用名詞或名詞短語命名，并加上后綴Logic

2.7文件夾命名

文件夾以功能模塊名稱，按照 Pascal 大小寫格式命名。
比如后端管理功能以及權(quán)限相關(guān)功能，全部放到Systems文件夾里。

3.注釋規(guī)范

3.1模塊（類）注釋規(guī)范

模塊開始必須以以下形式書寫模塊注釋：

///<summary>
	///模塊編號：<模塊編號，可以引用系統(tǒng)設(shè)計中的模塊編號>
	///作用：<對此類的描述，可以引用系統(tǒng)設(shè)計中的描述>
	///作者：作者中文名
	///編寫日期：<模塊創(chuàng)建日期，格式：YYYY-MM-DD>
	///</summary>
	
如果模塊有修改，則每次修改必須添加以下注釋：
	///<summary>
	///Log編號：<Log編號,從1開始一次增加>
	///修改描述：<對此修改的描述>
	///作者：修改者中文名
	///修改日期：<模塊修改日期，格式：YYYY-MM-DD>
	///</summary>

3.2類屬性注釋規(guī)范

在類的屬性必須以以下格式編寫屬性注釋：

/// <summary>
	///屬性說明
/// </summary>

3.3方法注釋規(guī)范

在類的方法聲明前必須以以下格式編寫注釋

/// <summary>
	/// 說明：<對該方法的說明>
	/// </summary>
	/// <param name="<參數(shù)名稱>"><參數(shù)說明></param>
/// <returns>
///<對方法返回值的說明，該說明必須明確說明返回的值代表什么含義>
/// </returns>

3.4代碼間注釋規(guī)范

代碼間注釋分為單行注釋和多行注釋：
單行注釋：

//<單行注釋>

多行注釋：

/*多行注釋1
多行注釋2
多行注釋3*/

代碼行數(shù)太多而不容易區(qū)分時注釋：

	/******************************************
	 *	代碼塊功能名稱
	 ******************************************/
//<單行注釋>
	或
/*多行注釋1
	多行注釋2*/

或者也可以使用下面方法：

/********* 代碼塊功能名稱開始 ************/
//<單行注釋>
//<單行注釋>
/********* 代碼塊功能名稱結(jié)束 ************/

注釋說明
A. 代碼中遇到語句塊時必須添加注釋（if,for,foreach,……）,添加的注釋必須能夠說明此語句塊的作用和實現(xiàn)手段（所用算法等等）。 對一個數(shù)值變量采用不是0,-1等的數(shù)值初始化，給出選擇該值的理由。
B. 盡量多點注釋，就算能一目了然的命名最好也順便寫一寫注釋，方便以后接收的人能更容易理解程序（方便不太懂英文的程序員）。
C. 如果因為某種原因使用了復(fù)雜艱澀的原理，為程序配備良好的文檔和更多的注釋。

4.編碼規(guī)范

1）縮進(jìn)和間隔：縮進(jìn)用TAB，不用 SPACES。

2）注釋需和代碼對齊。多使用#regedit和#endregion代碼塊。

3）在代碼中垂直對齊左括號和右括號。

if (x == 0)
{
	Response.Write("用戶編號必須輸入！");
}
    不允許以下情況：
if(x == 0) {
	Response.Write("用戶編號必須輸入！");
}

或者：

if(x == 0){ Response.Write("用戶編號必須輸入！"); }

4）適當(dāng)?shù)脑黾涌招?，來增加代碼的可讀性。
在下列情況下應(yīng)該有兩行空行：
? 同一文件的不同部分之間；
? 在類，接口以及彼此之間；
在下列情況之間應(yīng)該有一行空行：
? 方法之間；
? 局部變量和它后邊的語句之間；
? 方法內(nèi)的功能邏輯部分之間；

5）避免使用大文件。如果一個文件里的代碼超過300～400行，必須考慮將代碼分開到不同類中。當(dāng)然模板生成類與邏輯層類除外。

6）避免寫太長的方法。一個典型的方法代碼在1～25行之間。如果一個方法發(fā)代碼超過25行，應(yīng)該考慮將其分解為不同的方法。

7）為了防止在閱讀代碼時不得不滾動源代碼編輯器，每行代碼或注釋在1024*768的顯示頻率下不得超過一顯示屏

8）在大多數(shù)運算符之前和之后使用空格，這樣做時不會改變代碼的意圖卻可以使代碼容易閱讀。
例：

int j = i + k;  
而不應(yīng)寫為
int j=i+k;
括號和它里面的字符之間不應(yīng)該出現(xiàn)空格。括號應(yīng)該和它前邊的關(guān)鍵詞留有空格。
例：
while (true) 
{

};

但是方法名和左括號之間不應(yīng)該有空格。
參數(shù)之間的逗號后應(yīng)該加一空格。
例：

method1(int i1, int i2)

for語句里的表達(dá)式之間加一空格。
例：

for(expr1; expr2; expr3)

強制類型轉(zhuǎn)換時，在類型和變量之間加一空格。
例：

(int) i ; 

9）所有可供用戶輸入的字段值，必須需忽略前后空白后(不包含密碼)；在對字段值進(jìn)行有效性驗證。對提交進(jìn)數(shù)據(jù)庫的內(nèi)容必須進(jìn)行SQL注入過濾與XSS過濾。

10）一個方法只完成一個任務(wù)。不要把多個任務(wù)組合到一個方法中，即使那些任務(wù)非常小。

11）避免使用很多成員變量，聲明局部變量，并傳遞給方法。

12）不要在方法間共享成員變量，如果在幾個方法間共享一個成員變量，那就很難知道是哪個方法在什么時候修改了它的值。

13）不在代碼中使用具體的路徑和驅(qū)動器名，使用相對路徑，并使路徑可編程。永遠(yuǎn)別設(shè)想你的代碼是在“C:”盤運行。你不會知道，一些用戶在網(wǎng)絡(luò)或“Z:”盤運行程序。

14）應(yīng)用程序啟動時作些“自檢”并確保所需文件和附件在指定的位置。
如果需要的配置文件找不到，應(yīng)用程序需能自己創(chuàng)建使用默認(rèn)值的一份。如果在配置文件中發(fā)現(xiàn)錯誤值，應(yīng)用程序要拋出錯誤，給出提示消息告訴用戶正確值。

15）出現(xiàn)任何問題給用戶一個友好的提示，錯誤消息需能幫助用戶解決問題。
永遠(yuǎn)別用像“應(yīng)用程序出錯”，“發(fā)現(xiàn)一個錯誤”等錯誤消息。而應(yīng)給出像“更新數(shù)據(jù)庫失敗，請確保登陸id和密碼正確” 的具體消息。顯示錯誤消息時，除了說哪里錯了，還應(yīng)提示用戶如何解決問題。不要用像“更新數(shù)據(jù)庫失敗”這樣的，要提示用戶怎么做：“更新數(shù)據(jù)庫失敗，請確保登陸id和密碼正確”

16）錯誤處理和異常事件
不要“捕捉了異常卻什么也不做”。如果隱藏了一個異常，你將永遠(yuǎn)不知道異常到底發(fā)生了沒有。
發(fā)生異常時，給出友好的消息給用戶，但要精確記錄錯誤的所有可能細(xì)節(jié)，包括發(fā)生的時間，和相關(guān)方法，類名等。

別寫太大的 try-catch 模塊。如果需要，為每個執(zhí)行的任務(wù)編寫單獨的 try-catch 模塊。 這將幫你找出哪一段代碼產(chǎn)生異常，并給用戶發(fā)出特定的錯誤消息
如果應(yīng)用程序需要，可以編寫自己的異常類。自定義異常不應(yīng)從基類SystemException派生，而要繼承于. IApplicationException。文章來源地址http://www.zghlxwxcb.cn/news/detail-447615.html

到了這里，關(guān)于【軟件工程】軟件設(shè)計中的通用編碼規(guī)范的文章就介紹完了。如果您還想了解更多內(nèi)容，請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！