[書籍]重溫《Framework Design Guidelines》

来源:https://www.cnblogs.com/dino623/archive/2019/03/27/FrameworkDesignGuidelines.html
-Advertisement-
Play Games

1. 前言 最近重溫了《Framework Design Guidelines》。 《Framework Design Guidelines》中文名稱為《.NET設計規範 約定、慣用法與模式》，簡介如下： 數千名微軟精銳開發人員的經驗和智慧，最終濃縮在這本設計規範之中。與上一版相比，書中新增了許多評 ...


1. 前言

最近重溫了《Framework Design Guidelines》。

《Framework Design Guidelines》中文名稱為《.NET設計規範 約定、慣用法與模式》，簡介如下：

數千名微軟精銳開發人員的經驗和智慧，最終濃縮在這本設計規範之中。與上一版相比，書中新增了許多評註，解釋了相應規範的背景和歷史，從中你能聆聽到微軟技術大師Anders Hejlsberg、Jeffrey Richter和Paul Vick等的聲音，讀來令人興味盎然。

當年第一次讀時茅塞頓開，現在重溫還是獲益良多。雖是一本十年前的書，仍是值得推薦給初學者閱讀的一本好書。

2. 常見被違反的規範

今年升級一個核心代碼從很久以前的代碼改寫過來的軟體，各種不符合C#代碼規範的代碼讓我感到難以維護；去年系統工程師退休前留給我們的一個代碼更是讓我受到會心一擊。我使用C#多年來見到過很多不規範的代碼，於是試著參考書中的規範，列出其中一些來常見的錯誤以及一些問題。

2.1 命名

要把PascalCasing用於由多個單詞構成的名字空間、類型以及成員的名字。
要把camelCasing用於參數的名字。
不要使用匈牙利命名法。

也就是說參數要用camelCasing，其它所有能讓使用者看到的地方，包括命名空間、類名稱、屬性、函數等都要都要使用PascalCasing。（除非是ex、e、i等約定俗成的用法，或者其他特殊情況如工業標準、商標、歷史問題、遺留代碼、調用非托管代碼等。）

由於習慣問題，現在還經常見到匈牙利命名法如btnOk、strPwd，應修改為OkButton和Password。

要在命名欄位時使用PascalCasing大小寫風格。(適用於靜態公有欄位和靜態受保護欄位)
不要提供共有的或受保護的實例欄位。

.NET Core有更詳細的# Coding Style：

We use _camelCase for internal and private fields and use readonly where possible. Prefix internal and private instance fields with _, static fields with s_ and thread static fields with t_. When used on static fields, readonly should come after static (e.g. static readonly not readonly static). Public fields should be used sparingly and should use PascalCasing with no prefix when used.

雖然寫得很複雜，但我建議只有private的欄位、常量欄位和靜態只讀欄位。能被外部修改的欄位是危險的，所以欄位應該只有如下幾種形式：

private readonly string _id;

private string _userName;

private static bool s_valid = false;

public const int MaxValue = 0x7fffffff;

public static readonly Color Red = new Color(0x000FF);

要在命名資源鍵（Resource Key）時使用PascalCasing大小寫風格。

可是，我不覺得微軟自己有遵循這個規範啊。

總的來說，框架中除了函數的參數外所有可見的部分都應該使用PascalCasing風格，因為資源通常可以以屬性的方式被使用，所以資源的Key應該使用Pascal。可能因為很多時候資源的生成方式都是internal所以很多人都不遵守這個規範。

要在命名異常消息的資源時遵循下麵的命名約定。
資源標識符應該是異常的類型名加上一個簡短的異常標識符：
ArgumentExceptionIllegalCharacters
ArgumentExceptionInvalidName
ArgumentExceptionFileNameIsMalfrmed

我覺得這條規範也適用於一般的錯誤信息，我常常見到CreateUserErrorMessage1、CreateUserErrorMessage2這種資源名稱，改成CreateUserErrorInvalidUserName、CreateUserErrorInvalidPassword會比較好。

避免在命名基類時使用“Base”尾碼 -- 如果公共API中會用到這個類。

但是微軟自己的框架中就一大堆啊？不過這些都不常用，給一般用戶的API最好還是要遵守這條規範。

要用肯定性的短語（CanSeek而不是CantSeek）來命名布爾屬性。如果有幫助，還可以有選擇地給布爾屬性添加“Is”、“Can”或“Has”等首碼。

我覺得dont-首碼真的挺常見的，.NET Core的源碼里能搜出一大堆。無論如何我還是建議用肯定性的短語，否定性短語讓人混淆。

2.2 屬性

要在下列情況中使用方法而不要使用屬性

  • 該操作比欄位訪問要慢記個數量級。
  • 該操作返回一個數組。

這條規範有很多種情況，我只列出常見的兩種容易犯錯的情況。

第一種情況在WPF尤其常見，因為對XAML來說可以用於綁定的屬性好用很多，所以很多應該是方法的地方都使用屬性實現。

第二種情況在老代碼里很常見，別說返回數組，把數組做成全局變數大家一起複用都很常見，也許是因為當年記憶體很貴？

2.3 枚舉

要用單數名詞來命名枚舉類型，除非它表示的是位域（bit field）。
要用複數名詞來命名錶示位域的枚舉類型，這樣的枚舉類型也稱為標記枚舉（flag enum）。
不要給枚舉類型的名字添加“Enum”尾碼。
不要給枚舉類型的名字添加“Flag”或“Flags”尾碼。
不要給枚舉類型值的名字添加首碼。

//bad
public enum ImageMode
{
    ImageModeBitmap,
    ImageModeGrayScale,
    ImageModeRgb,
}

//good
public enum ImageMode
{
    Bitmap,
    GrayScale,
    Rgb,
}

枚舉的規範挺多的，但即使不特別提出來，參考.NET Framework中的枚舉也能很好地遵守這些規範。

2.4 集合

不要在公共API中使用ArrayList或List。
不要在公共API中使用Hashtable或Dictionary<TKey,Tvalue>。

這些類型的設計目的是為了用於內部實現，應該使用Collection、IEnumerable、或IDictionary<TKey,Tvalue>。

要在公共API中優先使用集合，避免使用數組。
不要提供可設置的集合屬性。
要用Collection或其子類--如果屬性或返回值表示可讀寫的集合。
要用ReadOnlyCollection或其子類，在少數情況下用IEnumerable，如果屬性或返回值表示只讀的屬性。

總的來說就是不要讓集合被人不明不白地修改了。現在我在處理的遺留代碼既使用數組作為屬性，又可Get和Set，畢竟是從很久以前一路修改過來的，當時的開發者應該也沒想到這些代碼現在會讓人這麼困擾吧。

要用描述集合中項目短語的複數形式來命名集合屬性，而不要使用短語的單數形式加“List”或“Collection”尾碼。

例如，要用Items、Objects，而不用ItemList、ObjectCollection。

2.5 異常

不要在框架代碼中捕獲System.Exception或System.SystemException，除非打算重新拋出。
不要在框架的代碼捕獲具體類型不確定的異常（比如System.Exception、System.SystemException，等等）時，把錯誤吞了。

總之不要捕獲System.Exception和System.SystemException，要讓用戶知道哪裡發生了問題。無論是不是框架的代碼，把異常吞了的做法都很讓人困擾，除非有充分的理由。

不要正常的控制流中使用異常，如果能夠避免的話。

很常見到捕獲了System.Exception做跳轉分支，以及明明有TryParse卻還是用TryCatch的代碼。

要在捕獲並重新拋出異常時使用空的throw語句。這是保持異常調用棧不變的最好方法。

總有人喜歡把異常封裝一下，然後就把異常類型改變，StackTrace或InnerException弄丟。

不要拋出System.Exception與System.SystemException。

2.6 事件

要用受保護的虛方法來觸發事件。
要讓觸發事件的受保護的方法帶一個參數，該參數的類型為事件參數類，該參數的名字應該為e。

public event EventHandler ContentRendered;

protected virtual void OnContentRendered(EventArgs e);

上面是WPF中Window類的代碼，WPF的各個控制項都有很好地執行這個規範，但自定義控制項及其它控制項庫則不是。

要用object作為事件處理函數的第一個參數的類型，並將其命名為sender。
要用System.EventArgs或其子類作為事件處理函數的第二個參數的類型，並將其命名為e。

同樣是DataContextChanged事件，WPF有遵循規範，但UWP則不然。我可以理解只有FrameworkElement會觸發DataContenxtChanged事件所以用FrameworkElement作為sender的類型，但將這個理論延伸到所有事件顯然不合適，到底UWP是怎麼回事？

//WPF
private void MainWindow_DataContextChanged(object sender, DependencyPropertyChangedEventArgs e)
{
    throw new NotImplementedException();
}

//UWP
private void MainPage_DataContextChanged(FrameworkElement sender, DataContextChangedEventArgs args)
{
    throw new NotImplementedException();
}

要用動詞或動詞短語來命名時間。
這樣的例子包括Clicked、Painting、DroppedDown，等等。
要用現在時和過去時來賦予事件名以之前和之後的概念。
例如，在視窗關閉之前發生的close事件應該命名為Closing，而在視窗關閉之後發生的應該命名為Closed。

所以WPF中Button的Click事件一直讓我很困擾，Xamarin改為Clicked就好多了。

還有一點比較困擾的是事件處理函數的命名，常常見到同一個類存在以下命名方式：

Loaded += OnLoaded;
_inlineBackButton.Click += OnInlineBackButtonClicked;
SizeChanged += MasterDetailsView_SizeChanged;

我一向比較喜歡用On-首碼加事件名稱的命名方式，因為這樣方便查找。但VisualStudio預設給的就是第三種，即“變數名+下劃線+事件名稱”的命名方式。這也很讓人困擾，不過反正不是給別人看的，隨意些也無所謂了。

3. 一些想法，關於XAML元素的命名

我不記得有在哪裡見過XAML上元素命名的規範（只看到XamlName語法），總之就是要符合C#的的通用命名規範。我個人建議XAML上元素使用PascalCasing，原因如下：

  1. 保持統一，基本上XAML中所有標簽都使用PascalCasing。
  2. UWP預設控制項模板也使用PascalCasing，下麵是UWP和WPF中ScrollViewer ControlTemplate的對比：
<!--UWP-->

<ScrollContentPresenter x:Name="ScrollContentPresenter"
                        Grid.RowSpan="2"
                        Grid.ColumnSpan="2"
                        ContentTemplate="{TemplateBinding ContentTemplate}"
                        Margin="{TemplateBinding Padding}" />
<Grid Grid.RowSpan="2"
      Grid.ColumnSpan="2" />
<ScrollBar x:Name="VerticalScrollBar"
           Grid.Column="1"
           IsTabStop="False"
           Maximum="{TemplateBinding ScrollableHeight}"
           Orientation="Vertical"
           Visibility="{TemplateBinding ComputedVerticalScrollBarVisibility}"
           Value="{TemplateBinding VerticalOffset}"
           ViewportSize="{TemplateBinding ViewportHeight}"
           HorizontalAlignment="Right" />
<ScrollBar x:Name="HorizontalScrollBar"
           IsTabStop="False"
           Maximum="{TemplateBinding ScrollableWidth}"
           Orientation="Horizontal"
           Grid.Row="1"
           Visibility="{TemplateBinding ComputedHorizontalScrollBarVisibility}"
           Value="{TemplateBinding HorizontalOffset}"
           ViewportSize="{TemplateBinding ViewportWidth}" />
<Border x:Name="ScrollBarSeparator"
        Grid.Row="1"
        Grid.Column="1"
        Opacity="0"
        Background="{ThemeResource ScrollViewerScrollBarSeparatorBackground}" />


<!--WPF-->

<ScrollContentPresenter x:Name="PART_ScrollContentPresenter"
                        CanContentScroll="{TemplateBinding CanContentScroll}"
                        CanHorizontallyScroll="False"
                        CanVerticallyScroll="False"
                        ContentTemplate="{TemplateBinding ContentTemplate}"
                        Content="{TemplateBinding Content}"
                        Grid.Column="0"
                        Margin="{TemplateBinding Padding}"
                        Grid.Row="0" />
<ScrollBar x:Name="PART_VerticalScrollBar"
           AutomationProperties.AutomationId="VerticalScrollBar"
           Cursor="Arrow"
           Grid.Column="1"
           Maximum="{TemplateBinding ScrollableHeight}"
           Minimum="0"
           Grid.Row="0"
           Visibility="{TemplateBinding ComputedVerticalScrollBarVisibility}"
           Value="{Binding VerticalOffset, Mode=OneWay, RelativeSource={RelativeSource TemplatedParent}}"
           ViewportSize="{TemplateBinding ViewportHeight}" />
<ScrollBar x:Name="PART_HorizontalScrollBar"
           AutomationProperties.AutomationId="HorizontalScrollBar"
           Cursor="Arrow"
           Grid.Column="0"
           Maximum="{TemplateBinding ScrollableWidth}"
           Minimum="0"
           Orientation="Horizontal"
           Grid.Row="1"
           Visibility="{TemplateBinding ComputedHorizontalScrollBarVisibility}"
           Value="{Binding HorizontalOffset, Mode=OneWay, RelativeSource={RelativeSource TemplatedParent}}"
           ViewportSize="{TemplateBinding ViewportWidth}" />

在WPF中TemplatePart的命名常會使用PART_首碼，這種古老的習慣現在還常常可以見到。Blend for VisualStudio已經移除“部件”視窗，使用PART_首碼可以標識控制項模板中的TemplatePart，基於這種理由也可以接受這種命名方式。

4. 結語

雖然很古老，但我還是把這本書推薦給初學者。docs.microsoft.com上有Framework Design Guidelines的文檔，但比書上精簡了很多，而且沒有來自微軟技術大師的評註，還是書好看，可惜09年出了第二版以來再沒有更新過，裡面一些規範也已經過時（如花括弧的用法）。

VisualStudio有很多工具可以用於規範代碼，好代碼是管出來的——.Net中的代碼規範工具及使用 這篇文章是很好的參考。也可以參考dotnet core 編程規範，林德熙(lindexi)的博客里有它的翻譯。


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • 持久層Mybatis3底層源碼分析，原理解析
    Mybatis-持久層的框架，功能是非常強大的，對於移動互聯網的高併發 和 高性能是非常有利的，相對於Hibernate全自動的ORM框架，Mybatis簡單，易於學習，sql編寫在xml文件中，和代碼分離，易於維護，屬於半ORM框架，對於面向用戶層面的互聯網業務性能和併發，可以通過sql優化解決一 ...
  • L2-022 重排鏈表（鏈表）
    題目： 給定一個單鏈表 L​1​​→L​2​​→⋯→L​n−1​​→L​n​​，請編寫程式將鏈表重新排列為 L​n​​→L​1​​→L​n−1​​→L​2​​→⋯。例如：給定L為1→2→3→4→5→6，則輸出應該為6→1→5→2→4→3。 輸入格式： 每個輸入包含1個測試用例。每個測試用例第1行給出 ...
  • java學習筆記10
    java方法返回值與參數 例： public void a(int c){ //void 說明此方法沒有返回值，括弧里的叫參數，有數據類型和變數名組成，在方法里叫做形式參數簡稱形參。 } public int a(){ //這裡說明返回值是int整型，4位元組。 //返回關鍵字是return retu ...
  • 分散式鎖探討
    一、分散式鎖背景 a、什麼是鎖？ 從使用場景定義：當存在多個線程可以同時改變某個變數時，就需要對變數或代碼塊做同步，使其在修改這種變數時能夠線性執行消除併發修改變數。 鎖的實現方式有多種，只要能滿足所有線程都能看得到這個鎖標記即可。 Java中常見的鎖： synchronized Reentrant ...
  • mybaits攔截器+自定義註解
    實現目的：為了存儲了公共字典表主鍵的其他表在查詢的時候不用關聯查詢（所以攔截位置位於mybaits語句查詢得出結果集後） 項目環境 ：springboot+mybaits 實現步驟：自定義註解——自定義實現mybaits攔截器——註冊mybaits攔截器 一、自定義註解 1.1 代碼示例 @Targ ...
  • Java基礎學習-基本數據類型變數的定義和使用
    註意：如果使用notepad++編碼，在cmd控制台編譯時報錯（編碼GBK的不可映射字元），可以參考如下鏈接進行設置：https://jingyan.baidu.com/article/e3c78d649a56233c4c85f502.html 1.編寫案例演示每種不同數據類型的變數定義 /* 變數 ...
  • Python學習 ：socket基礎
    socket基礎 什麼是socket？ - socket為介面通道，內部封裝了IP地址、埠、協議等信息；我們可以看作是以前的通過電話機撥號上網的年代，socket即為電話線 socket通信流程 我們通過下麵的圖來瞭解socket的通信流程 流程描述： - 1 伺服器根據地址類型（ipv4,ipv ...
  • Flask 系列之 SQLAlchemy
    SQLAlchemy 是一種 ORM 框架，通過使用它，可以大大簡化我們對資料庫的操作，不用再寫各種複雜的 了。 說明 操作系統：Windows 10 Python 版本：3.7x 虛擬環境管理器：virtualenv 代碼編輯器：VS Code 實驗目標 實現網站與 mysql 資料庫的連接和 C ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發（一）：使用.NET MAUI開發第一個安卓APP
    移動開發（一）：使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說，近來想嘗試開發一款安卓APP，考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP，畢竟是使用Visual Studio開發工具，使用起來也比較的順手，結合微軟官方的教程進行了安卓 ...
  • wpf ToggleButton選中效果和一個登錄界面
    前言 QuestPDF 是一個開源 .NET 庫，用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫，它徹底改變了我們生成 PDF 文檔的方 ...
  • 彈幕樹洞項目功能新增篇
    項目地址 項目後端地址： https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址： ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址： http://tree ...
  • 第27篇 sqlserver2022詳細安裝步驟
    話不多說，直接開乾 一.下載 1.官方鏈接下載： https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe，運行開始下載SQL server； 二. ...
  • .NET 開源高性能 MQTT 類庫
    前言 隨著物聯網（IoT）技術的迅猛發展，MQTT（消息隊列遙測傳輸）協議憑藉其輕量級和高效性，已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫，為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog文檔翻譯系列（六） - 可用的接收器、增強器、格式化輸出
    Serilog支持多種接收器用於日誌存儲，增強器用於添加屬性，LogContext管理動態屬性，支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項，適用於不同需求。 ...
  • 警惕 Visual Studio 屬性求值副作用導致邏輯不符合預期
    目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據，爬取信息時需要模擬瀏覽器行為，否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下： 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • [使用目前最新版]HybridCLR6.9.0+YooAsset2.2.4實現純C# Unity熱更新方案 (一)
    1.前言 什麼是熱更新 游戲或者軟體更新時，無需重新下載客戶端進行安裝，而是在應用程式啟動的情況下，在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR，Xlua，ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles，Addressable， ...
  • 在 ASP.NET Core Web API 中使用操作篩選器統一處理通用操作
    本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺，其實像阿裡雲，騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後，它會送 ...
  • 第28篇 如何.net中實現高效可靠數據同步api
    通過以下方式可以高效，並保證數據同步的可靠性 1.API設計 使用RESTful設計，確保API端點明確，並使用適當的HTTP方法（如POST用於創建，PUT用於更新）。 設計清晰的請求和響應模型，以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證，確保接收到的數據符合預期格 ...
所有分類