#81 出神入化的用介面 第四集 修改共用的介面 part.2

這一篇文章是上一集的延伸，再來說明新版本 interface 的後續實際使用的情況．先將此篇文章要解決問題再描述一次．想像一家公司出版了一套軟體，而這個產品裡包含了許多的元件檔案 (.dll)，而且每一個元件是由不同的團隊產生．每個元件可以有獨立的發行時間，也就是說當 A 團隊要釋出新功能的版本時，他們可以自行釋出．在客戶端裡，可以透過該軟體裡的更新程式來下載並且安裝 A 團隊所製做的新版本元件．由於各元件釋出的時間並非一致，因此元件之間的互動將變得有挑戰性．

A 團隊裡的某些功能是透過 B 團隊的元件所完成的．例如，A 團隊提供的功能裡有一項是計算產品折扣，而這項功能的細節實作者其實是 B 團隊，因此 B 團隊會提供 interface component 給 A 團隊使用，如:



因此，在 A 團隊的程式碼裡，將可能利用下述的程式碼得到實做該介面的物件，然後來進行折扣計算，如:



接著，A, B 團隊從產品經理接收到新需求，他們必須提供一個新的功能 - 回饋金 (cash back)．因此，比較簡單的做法便是將上述的 interface 加以延伸．但如上一集文章所提，B 團隊不能直接改 IProductUtils，所以他們必須要製造一個新的 interface，並且繼承自 IProductUtils．



A 團隊接著將他們的程式碼修改如下:



若 A 團隊用上述的方式更改程式，則有可能發生錯誤．當某個用戶端使用新版的 A 團隊程式而且用了舊版的 B 團隊程式，則執行到上述程式碼時，就會發生 TypeLoadException 的錯誤，因為此時電腦裡是舊版的 B 團隊元件，所以 runtime 看不懂 IProductUtils2，對它而言，這是一個 unknown type．

為了防止上述的錯誤發生，A 團隊必須採用一些方法來辨別 runtime 所載入的是舊版或新版的元件．可能的方法如下:

讓 B 團隊為不同版本的元件使用不同的檔案名稱．如 BContract.1.dll 和 BContract.1.1.dll 等．B 團隊發行新版本時，可將兩個新舊兩版的 contract dll 一起釋出，同時在實做的程式碼裡也會同時實做新舊兩版的 interfaces．所以，A 團隊若用舊版 (BContract.1.dll)，則 A 團隊只會看到 IProductUtil，若用新版 (BContract.1.1.dll)，可看到 IProductUtil 和 IProductUtil2．這樣做的好處是讓新舊兩版的 interface 位於不同的元件裡，當其他團隊取得舊版時，其他團隊只能看到 IProductUtil．使用新版時，則可看到兩個 interfaces．利用實體檔案區別同一個功能的新舊版本．壞處就是可能會造成過多的元件檔案．

讓 B 團隊將新舊版本的 interfaces 寫在同一個元件檔案裡，如 BContact.dll．這樣做將讓 A 團隊無法從元件檔名上知道他們正使用的是新版還是舊版．因此，就必須透過程式碼來解決這問題．A 團隊為了處理新舊兩版的情況，當他們載入 B 團隊的元件時，他們可先嘗試使用 IProductUtil2，若 IProductUtil2 使用時發生 TypeLoadException，則表示 B 團隊的元件是舊版的．此時 A 團隊便可以把回饋金功能的相關 UI 畫面關閉．請參考下列程式碼來看 A 團隊如何使用正確的版本．



透過上述的方式，當 runtime 執行到 line 12 準備進入 TryGetNewVersion() 時，如果此時 A 團隊使用的是舊版 B 團隊元件，則 runtime 便會發生 TypeLoadException 的錯誤，因為 line 28 的 IPorductUtils2 是一個 unknown type，並且此錯誤會在 line 18 被抓住．接著 A 團隊便可以關閉回饋金的相關功能．如果 A 團隊使用新版本，則不會發生 TypeLoadException．只要能順利取得正確的物件就能呼叫 GetCashBack() 來得到回饋金的金額．若用這個方法，則 A 團隊必須使用 B 團隊的新版本元件在他們的編輯環境裡，才不會發生 build fail (unknown type) 的情況．

這一篇文章提到的情境應該不會是大多數人的情境，畢竟同一個軟體產品裡每一個元件可以有不同的釋出時程是很少見的．如果你的工作情況真的有符合這樣的情境，希望這篇文章能給你一種解法來解決這情境的問題．若你的解法不同，也歡迎你分享給我．

Hope it helps,

閱讀全文

#80 寫程式的參考準則 (coding guideline) - C# 篇

曾有一些朋友問我，在微軟公司裡是否有寫程式的準則 (coding guideline)．這件事因不同的團隊而異，大部份的團隊都會依循 MSDN 文件裡的建議，但並非每一個團隊都有文件記錄這些準則．以前我在 Windows 部門裡的某個團隊就正好有文件說明 C# coding guideline．除了 C# coding guideline 以外，還有其他的文件，例如 code review 文件, database 開發文件等等．在這篇文章中，我將從 C# coding guideline 開始寫起．這些 coding guideline 不是什麼秘密，很多都是來自 MSDN 的文件．若你的團隊也需要一份 C# coding guideline, 希望能派的上用場．

1. 在一份 C# 原始碼裡，別有 Tab , space 並存．這一個可以善用 Visual Studio 的編輯器設定幫你解決．一般來說，我們用 space 來取代 tab，例如一個 tab 等於四個 spaces.

2. 一行程式碼的字數通常設定在 120 個字元左右．為了方便閱讀，若有一個 api 有多個參數需要傳入，將多個參數分行排列，如下例


3. 有關設定變數 (variable)，盡可能地將其 scoping 範圍找小一點的．

4. 變數宣告時不一定要馬上給初始值 (initialize)．用到此變數時在給即可．若需要給一個初始值，請給一個有意義的值做為初始值．這邊所謂有意義的初始值不代表該資料結構的預設值．如 int count = 0; ，這是多此一舉的行為．

5. Global field 前面加上 _ ．若是 local variable，則不用．
如 int _memberCount;  
     int memberCount;

6. 相同型別的變數要分行宣告．別擠在一行一起宣告，應分行．如:
int foo;
int bar;
int baz;

7. 對於常數型的變數 (內容不會變動) 記得使用 const 宣告. 如:
private const int _defaultCount = 100;

另外，對於這類常數型變數，最好能加上一個 comment 用來說明為何選用此內容. 如:
// 100 is chosen because of the size limit of the queue
private const int _defaultCount = 100;

8. 對於多個性質相關的常數型變數，可以考慮將他們整合在一個 static class 裡宣告並使用，如:

可改成


9. 用 string.Empty 來取代 ""

10. 用 string.IsNullOrWhiteSpace() 來檢查字串是否為 null 或是空白.

11. 對於一些 “應用值”，不應該 “hard-code”，而是該透過其他較彈性的方式取得 (像 Configuration)．如
網路連線重試次數，timeout 時間, thread 數量, 資料庫連線字串等等

12. 在 if , while , for, foreach, return 前多個空行，以便於閱讀.

13. Class 裡的 method 之間有一個空白行．

14. 若有需要，善用 #region, #endregion 將相關的程式放在同一個區塊裡．同時 #region 之間也該有一個空白行.

15. 善用 IDE 裡的編輯器幫助你處理好空白的事情．如


16. 遇到一些特別情況時，善用 comment 以便未來工作．寫 comment 時不用一行一行寫 (inline)，請在適當地方用一塊區域來說明程式的運作目的．


17. 對於 public method 都該檢查輸入參數是否符合你的預期．如:


18. 該有括號的地方都打上去，別偷懶不打．如:


19. public method, property 等一律使用 PascalCasing ，而非 public 改用 camelCasing. 如:
public int GetMyReward();
public string MyName {get; set;}

private int getMyReward();
private string _myName;

20. 為 variable, property, method, class, interface 取名是件重要的事情．取一個完整的名稱，別用簡稱．如 使用 GetConsoleWindow() 而不用 GetConWin()

21. Namespace 命名以 PascalCasing 方式，名字應以名詞為主．如: System.Security

22. Class 命名以 PascalCasing 方式，名字應以名詞為主，如 StreamReader, DataCollector 等

23. Interface 命名以 PascalCasing 方式，通常在最前面加上 I ，名字應以名詞為主，如 IList, IReadOnlyCollection 等

24. Variable 與 parameter 命名以 camelCasing 方式，名字應以名詞為主，如:
public int ToInt32(string itemValue, int itemCount);

25. Method 命名以 PascalCasing 方式，名字應以動詞為主，如:
ToString(), Write(), ExecuteCommand();

26. Property 命名以 PascalCasing 方式，名字應以名詞為主，如:
public int Length { get; set; }

27. Event 命名以 PascalCasing 方式，名字應以動詞為主，如:
public event EventHandler ObjectChanged;

28. Public field 命名以 PascalCasing 方式，而 private field 以 camelCasing 方式，名字應以名詞為主，如:
public TimeSpan Timeout;
private TimeSpan _firstTimeout;

29. Enum 命名以 PascalCasing 方式，名字應以名詞為主，如:
FileMode
{
Open,
Create,
Append,
}

30. Class 的名字通常和對應的 Interface 名字有關係，如:


31. 大部份的情況下, Enum 最好要加上 None 元素用來代表該 enum 用不到的情況下，並且將它設定為 0．如:


32. Enum 若是 Flags 的屬性，別在名字加上 Flag，可用複數名詞來代表. 如


33. 為了便於閱讀和 code review，將關聯性高的 class 成員寫在相鄰的位置．

34. 一個檔案最好只有一個 class，並且檔案名字與 class 名字一致．若是 nested class 或是一些簡單且臨時在程式間用的 class 除外．

35. 所有的宣告都應加上 public, private, internal．若是只在一個 method 裡使用的臨時變數可以忽略．

36. 在 switch 裡要加上 default: ，即使它的內容是空的，也要加上．

37. 要產生準確的 exception．如，當你檢查參數是否為空時，就該用 ArgumentNullException 而不是用 ArgumentException．

38. 產生 exception 時，要產生有意義且可知道錯誤細節與解決方法的 exception，不該把許多可能會發生錯誤的 code 放在一個 try block 裡，然後只有一個 catch (Exception ex).

39. 當處理商業邏輯時，很可能找不到適合的 exception type，此時應自行建立自訂的 exception．

40. Exception 產生時不應該影響程式的正常流程，並且 exception 產生時需被處理，例如 log．

41. 在 try-catch 裡若使用到一些資源，可在 finally block 裡釋放．如:


42. 在你的程式裡，在最上層 (可能是在 UI 層) 要能抓住所有可能會發生的 exception，做好相對應的處理或畫面顯示，避免程式中斷．

43. 在 catch block 裡應該都為該 exception 做些處理動作，而不是空白 (什麼事都不做)．除非，程式裡已有邏輯在處理那段錯誤，如:


44. 不用重覆拋出 exception．應該加一些錯誤處理機制並且只需要 throw 即可．如:


45. 對於有實做 IDisposable 的 class 應善用 using 來確保資源能適時適當地被釋放．如:


別在 try-finally 裡使用 Dispose，如:


46. 盡可能使用 generic collection 來儲存物件，例如使用 List<T> 而不用 ArrayList．

47. 所有的 public class, property, method 都應該要有 XML 文件註解，如:


48. 有適合的語法糖時就使用，以便於閱讀．如:


49. 在不影響程式邏輯的情況下，應把程式碼編排縮排量減少．如:


50. Public method 的參數應盡量使用 interface，如:


51. 若無特別需求，為每個非同步呼叫加上 ConfigureAwait(false)

52. 若無特別需求，不自行建立 Thead ，一律使用 Task 讓 .NET threadpool 來管理相關資源．

53. 多個 Task 有執行順序時，善用 ContinueWith(), WhenAll(), 或 WhenAny()，而不該用 Task.Delay．

閱讀全文