The Will Will Web

記載著 Will 在網路世界的學習心得與技術分享

C# 編碼規範(Coding Standard)參考文件

我長久一來一直苦惱於不知道如何訂定 C# 編碼規範(Coding Standard),雖然很久以前我就有看到微軟的開發類別庫的設計方針文件,不過內容過於嚴謹,況且我們的工程師大多是開發 ASP.NET 居多,並不常開發類別庫(Class Libray),所以我若用 MSDN 的開發類別庫的設計方針要求工程師們可能會有點不切實際。

所以我自己與其他工程師之間,其實並沒有什麼特別明訂的 Coding Standard,反而我們十分倚賴 Visual Studio 的預設命名規則來開發,一來工程師不用特別記憶有哪些規則,二來透過工具產生名稱其實是蠻方便的。即便沒什麼規定,不過我在開發 ASP.NET 的時候的確有幾個最基本的原則:

  1. 如果同一類型的物件很多(例如在 DetailsView 中有很多欄位),會將變數的型別簡稱(如:btn)訂在後面。

    例如:在套用某個資料庫欄位 Name 並使用 TextBox 控制項時,我會將 ID 命名成  Name_btn

    當在寫 Code Behind 程式時,透過 Intelli-sense 打欄位前幾碼就可以馬上找到物件,不用選擇太多,如果 btn 寫在前面,在 Intelli-sense 時就會選一推物件,反而造成困擾!
  2. 如果那一頁的物件數量少且型別也不一樣,我才會將型別簡稱打在前面。

總之,唯一目的就是讓 Coding 的工作比較有效率的進行。不過,這樣的開發模式在很多情況下卻不是真的有那麼方便,例如說專案大、人多的案子,程式碼也就會跟著多了起來,整個專案程式碼就真的很容易亂掉。另外,有些小型的 Console Program 因為程式過於獨立,所以不同的工程師所寫的程式碼南轅北轍。因為我時常在 Review 我們公司工程師所寫的程式碼,有時後真的 Review 的很痛苦,我想我應該要好好的訂定出一個編碼規範了。

昨天在 Lance Hunt 的部落格發現有一份精簡版的編碼規範( C# Coding Standards document ),看完後覺得還蠻不賴的。這份文件內容不多,連封面、版權宣告、目錄、包括所有內容全部加起來才 22 頁而已,內容包括了有 命名方針(Naming Conventions), 編碼樣式(Coding Style), C# 語言用法(Language Usage), 以及物件模型與API設計(Object Model Design)等主題,最後還有列出一些參考連結。

此文件中所有的內容都是以清單與表格的方式呈現,並包括一些錯誤範例與正確範例的對照,文件架構十分清楚,英文單字的使用我覺得都應該是大家容易瞭解且常看到的單字,且用字也十分精簡,所以閱讀起來並不會很吃力。

Lance Hunt 撰寫這份文件的目標如下(譯自 C# Coding Standards document 網頁):

  • 涵蓋所有在 C# 中主要的語言特性
  • 提供編碼樣式與語言用法等指導方針(並非提供 "撰寫語法" 的規範)
  • 大多編碼規範都有提供程式碼範例
  • 有結構的描述規範,方便閱讀與使用
  • 定義清楚、明瞭的規範
  • 使用一致的詞彙與規範樣式
  • 僅提供在實務上清楚且明確定義的規範
  • 讓開發人員透過這份文件的規範避開一些常見的程式撰寫問題
    原文: Lead developers to a "pit of success" and avoid common "pits of failure"
    譯註: 引領開發人員跳入「成功的圈套」以及避開常見的「失敗陷阱」

相關連結