在過去的幾年裡，我們編寫了大量的 Dart 程式碼，並從中收穫了很多經驗和教訓。我們將與你分享這些經驗，這些經驗將有助於你編寫出一致、健壯、高效的程式碼。這裡包含兩主題：

1. 保持一致 當談論到格式、命名以及引數的相關規則時，哪種規則更好，得出的結論通常是主觀且無法達成一致的。但我們知道的是，客觀上保持 一致 是非常有益的。

   如果兩段程式碼看起來不同，那它們就應該有不同的含義。當一段突出的程式碼吸引到你的注意時，那它就應該有吸引你的理由。

2. 保持簡潔 Dart 會讓開發者感到很親切，因為它繼承了許多與 C、Java、JavaScript 及其他語言相同的陳述式和表示式語法。我們之所以開發 Dart 語言，是因為這些語言依然有很大的改進的空間。我們提供了很多新的特性，比如字串插值、初始化正規化等，以幫助你更簡單、更輕鬆地表達意圖。

   如果有多種方式來描述一件事情，那麼你通常應該選擇其中最簡潔的方式。這並不意味著你要像 code golf（程式碼高爾夫挑戰賽）一樣將所有程式碼塞到一行中。而是應該讓程式碼變得 簡約 而非 密集。

指南

為了便於理解，這裡我們將指南分成了幾個部分：

• 風格指南 – 該部分定義了佈局和組織程式碼的規則，或者說是 dart format 不能為你格式化的那些程式碼的佈局和組織規則。風格指南還為你指定了識別符號的格式，比如：駝峰式大小寫、下劃線的使用等等。

• 註釋指南 – 該部分會告訴你註釋中應該包含哪些內容。包括文件註釋以及常規的普通程式碼註釋。

• 使用指南 – 該部分將教你如何充分利用語言特性來實現相關功能。比如你可以在該部分找到如何利用陳述式或表示式來實現某個功能。

• 設計指南 – 該部分是最易理解但是覆蓋範圍最廣的。其涵蓋了我們所總結的為庫設計一致、可用 API 的經驗。比如這些 API 的型別簽名或宣告的說明則會在這裡找到。

有關所有指南的連結，請查閱 概覽。

如何閱讀這些指南

每個指南都分為了幾個部分。每個部分包含一些詳細的準則。每條準則都以下面其中的一個詞作為開頭：

• 要 準則所描述的內容應該始終被遵守。不應該以任何的理由來偏離違背這些準則。

• 不要 準則所描述的內容是相反的：描述的準則不是一個好主意。幸運的是，我們不會像其他語言有那麼多這樣的準則，因為我們沒有太多的歷史包袱。

• 推薦 準則所描述的內容 應該 被遵守。但是在有些情況下，可能有更好的或者更合理的做法。請確保在你完全理解準則的情況下，再忽視這些準則。

• 避免 該單詞描述的準則與 “推薦” 描述的準則相反：顯然，這些事不應該做，但不排除在極少數場合下有充分的理由可以做。

• 考慮 準則所描述的內容可以遵守也可以不遵守。取決於具體的情況、習慣做法以及自己的偏好。

某些準則描述了規則 不 適用的 例外情況。當這些例外列出時，也有可能不是詳盡的—你可能還需要對其它的情況作出判斷。

這聽起來好像有點小題大做。其實並沒有那麼糟糕。大部分的準則都是常識，也符合我們的認知。最終要達到的目標是寫出優雅，可讀，可維護的程式碼。

Dart 分析器提供了一個 Linter 工具，可以幫助你編寫優秀的、一致性的以及符合各種指南的程式碼。如果存在一個或者多個 linter 規則 來幫助你遵循某個指南準則，那麼這些指南的連結也會有顯示。比如下面的範例：

Linter rule: unnecessary_getters_setters

學習如何使用 linter，請查閱文件 啟用 linter 規則，以及可用的各種 linter 規則。

術語表

為了使指南保持簡潔，我們使用一些簡寫術語來指代不同的 Dart 結構。

• 庫成員 表示一個最上層欄位、Getter 或 Setter 方法、或函式。基本而言，任何最上層的東西都不會是一種型別。

• 類成員 表示類內部宣告的建構函式、欄位、Getter 或 Setter 方法、函式或運運算元。類成員可以是例項或靜態的，也可以是抽象或具體的。

• 成員 可以表示是一個函式庫成員或者類成員。

• 變數 通常指的是最上層變數、引數和區域變數。它不包括靜態或例項欄位。

• 型別 表示所有命名型別的宣告：一個類別、typedef 或列舉。

• 屬性 表示最上層變數、Getter 和 Setter 方法（位於類中或最上層，可以是例項或靜態的）或欄位（例項或靜態的）。基本上是任何類似欄位的命名結構都可以稱為屬性。

所有準則摘要