內容

在過去幾年,我們撰寫了大量的 Dart 程式碼,並學到了許多關於什麼有用、什麼沒用的知識。我們與你分享這些知識,以便你也能撰寫一致、強健、快速的程式碼。有兩個主要的重點

  1. 保持一致性。在格式化和大小寫等方面,關於哪種更好的爭論是主觀的,而且無法解決。我們所知道的是,保持一致性在客觀上是有幫助的。

    如果兩段程式碼看起來不同,那應該是因為它們在某些有意義的方式上不同。當一段程式碼脫穎而出並吸引你的目光時,它應該出於有用的原因。

  2. 簡潔。Dart 被設計為易於理解,因此它繼承了許多與 C、Java、JavaScript 和其他語言相同的陳述和表達式。但我們之所以創建 Dart,是因為有很大的空間可以改進這些語言提供的功能。我們添加了一堆功能,從字串內插到初始化形式參數,以幫助你更簡單、更輕鬆地表達你的意圖。

    如果有多種方法可以表達某件事,你通常應該選擇最簡潔的方法。這並不是說你應該程式碼高爾夫,將整個程式塞進一行中。目標是經濟的程式碼,而不是密集的程式碼。

指南

#

我們將指南分成幾個單獨的頁面,以便於理解

  • 樣式指南 – 這定義了佈局和組織程式碼的規則,或至少dart format 沒有為你處理的部分。樣式指南還指定了識別碼的格式:camelCaseusing_underscores 等。

  • 文件指南 – 這告訴你你需要知道的所有關於註解內部內容的信息。包括文件註解和常規的、普通的程式碼註解。

  • 用法指南 – 這教你如何最佳利用語言功能來實作行為。如果它在陳述或表達式中,這裡有說明。

  • 設計指南 – 這是最軟性的指南,但範圍最廣。它涵蓋了我們在為函式庫設計一致、可用的 API 方面學到的知識。如果它在類型簽章或宣告中,這會說明它。

有關所有指南的連結,請參閱摘要

如何閱讀指南

#

每個指南都分成幾個部分。部分包含指南列表。每個指南都從以下單字之一開始

  • 執行指南描述應該始終遵循的做法。幾乎永遠沒有理由偏離它們。

  • 不執行指南是相反的:幾乎永遠不是好主意的東西。希望我們沒有像其他語言那樣有這麼多,因為我們有較少的歷史包袱。

  • 建議準則是你應該遵循的實務。不過,在某些情況下,採取其他做法可能是合理的。只要確保你在忽略準則時,了解其所有影響即可。

  • 避免準則與「建議」相反:某些你不應該做的事,但在某些罕見情況下,可能會有正當理由這麼做。

  • 考慮準則是你可能想要或不想要遵循的實務,視情況、先例和你的個人偏好而定。

有些準則會說明規則適用的例外。列出例外時,可能無法涵蓋所有情況,你可能仍需要對其他案例自行判斷。

這聽起來像是如果你沒有正確繫鞋帶,警察就會破門而入。事情沒那麼嚴重。這裡的大部分準則都是常識,而我們都是理性的人。目標一如往常,是寫出美觀、可讀且可維護的程式碼。

Dart 分析器提供一個 linter,協助你撰寫遵循這些和其他準則的良好且一致的程式碼。如果存在一個或多個linter 規則可以協助你遵循準則,則準則會連結到這些規則。連結使用下列格式

linter 規則:unnecessary_getters_setters

如需了解如何使用 linter,請參閱啟用 linter 規則linter 規則清單。

詞彙表

#

為了讓準則簡潔,我們使用一些簡稱來指稱不同的 Dart 建構。

  • 函式庫成員是頂層欄位、getter、setter 或函式。基本上,頂層的任何非類型項目。

  • 類別成員是在類別內宣告的建構函式、欄位、getter、setter、函式或運算子。類別成員可以是實例或靜態、抽象或具體。

  • 成員是函式庫成員或類別成員。

  • 變數在一般使用時,是指頂層變數、參數和區域變數。不包括靜態或實例欄位。

  • 類型是任何命名類型宣告:類別、typedef 或列舉。

  • 屬性是頂層變數、getter(在類別內或頂層、實例或靜態)、setter(相同)或欄位(實例或靜態)。大致上是任何「類似欄位」的命名建構。

所有規則摘要

#

用法

#

函式庫

Null

字串

集合

函式

變數

成員

建構函式

錯誤處理

非同步

設計

#

名稱

函式庫

類別和混合

建構函式

成員

類型

參數

相等性