Dart 風格指南

摘要： 識別符號 在 Dart 中識別符號有三種風格： 大寫駝峰 ：每個單詞的第一個字母大寫，包括第一個單詞。 小寫駝峰 ：每個單詞的第一個字母大寫，除了 第一個單詞一直小寫，即使第一個單詞是...

識別符號

在 Dart 中識別符號有三種風格：

• 大寫駝峰 ：每個單詞的第一個字母大寫，包括第一個單詞。
• 小寫駝峰 ：每個單詞的第一個字母大寫，除了 第一個單詞一直小寫，即使第一個單詞是縮寫。
• 小寫加下劃線 ：只使用小寫字母，即使是縮寫，然後使用下劃線_ 分隔。

型別名使用大寫駝峰

類，列舉，自定義型別和引數型別，應該使用大寫駝峰，且不能使用分隔符。

class SliderMenu { ... }

class HttpRequest { ... }

typedef bool Predicate<T>(T value);

甚至包括作為元資料註解的類。

class Foo {
const Foo([arg]);
}

@Foo(anArg)
class A { ... }

@Foo()
class B { ... }

如果註解類的建構函式沒有引數，可以建立一個單獨的小寫駝峰 常量。

const foo = const Foo();

@foo
class C { ... }

庫和原始檔名使用小寫加下劃線

一些檔案系統是不區分大小寫的，所以許多專案要求檔名全小寫。使用分隔符使得那種方式下名字仍然可讀。使用下劃線作為分隔符確保名字仍然是有效的 Dart 識別符號，這可能很有用，如果後續支援符號匯入。

library peg_parser.source_scanner;

import 'file_system.dart';
import 'slider_menu.dart';

注意：該指南指定了如何命名一個庫，如果你選擇命名它。如果你想在檔案中省略 library 指令也是可以的。

匯入別名使用小寫加下劃線

import 'dart:math' as math;
import 'package:angular_components/angular_components'
as angular_components;
import 'package:js/js.dart' as js;

其它識別符號使用小寫駝峰

類成員，頂級的定義，變數，引數，命名引數使用小寫駝峰。

var item;

HttpRequest httpRequest;

void align(bool clearItems) {
// ...
}

推薦常量名使用小寫駝峰

在新程式碼中，對常量包括列舉值使用小寫駝峰。在已存在程式碼繼續使用全部大寫加下劃線，和之前保持一直。

const pi = 3.14;
const defaultTimeout = 1000;
final urlScheme = new RegExp('^([a-z]+):');

class Dice {
static final numberGenerator = new Random();
}

超過兩個字母的首字母縮略詞以及縮寫詞，應該大寫

大寫首字母縮略詞有點難以閱讀，並且多個相鄰的縮寫可能導致模稜兩可的名字。例如，一個以HTTPSFTP 開始的名字，沒有辦法判斷提及的是HTTPS FTP 還是HTTP SFTP 。

為了避免這種情況，除了兩個字母的首字母縮略詞以及縮寫詞，其它的還是像常規單詞那樣首字母大寫。（兩個字母的縮寫詞，像 ID 和 Mr. 仍然首字母大寫。）

HttpConnectionInfo
uiHandler
IOStream
HttpRequest
Id
DB

順序

為了保持檔案的整潔，我們規定指令出現的順序。每個部分應該使用空行隔開。

在其它匯入之前匯入 “dart:”

import 'dart:async';
import 'dart:html';

import 'package:bar/bar.dart';
import 'package:foo/foo.dart';

在相對匯入之前匯入 “package:”

import 'package:bar/bar.dart';
import 'package:foo/foo.dart';

import 'util.dart';

在其它匯入前匯入第三方 “package:”

import 'package:bar/bar.dart';
import 'package:foo/foo.dart';

import 'package:my_package/util.dart';

在所有匯入之後的單獨部分指定匯出

import 'src/error.dart';
import 'src/foo_bar.dart';

export 'src/error.dart';

各部分內按字母順序排序

import 'package:bar/bar.dart';
import 'package:foo/foo.dart';

import 'foo.dart';
import 'foo/foo.dart';

格式化

像其它語言，Dart 忽略空格。然而，人們不會。一致的空格風格確保人們看到的程式碼和編譯器做的一樣。

格式化是乏味的工作，在重構時特別花費時間。幸運的是，你不需要擔心它。我們提供一個名為ofollow,noindex">dartfmt 的自動程式碼格式化程式，它可以幫你做這些。官方對 Dart 的空格處理規則是根據 dartfmt 生成的。

避免一行的長度超過 80 個字元

可讀性研究表明，過長的文字不適合閱讀，因為當你看到下一行開始的時候眼睛移動的距離過大。這就是為什麼新聞和雜誌使用多列的文字。

如果實際上你發現自己需要的行長度超過 80 個字元，我們的經驗是你的程式碼可能太冗長了，可能需要更短小簡潔。主要的問題通常是VeryLongCamelCaseClassNames 。問問你自己，“有必要名字中的每個單詞都告訴我們一些型別資訊或防止命名衝突嗎？如果不，考慮省略它。

注意 dartfmt 為你做 99% 的事，但最後的 1% 是你的。它不會分離字串字面量來符合 80 個字元，所以你必須手動去做。

有一個例外，是在匯入和匯出中，包含 URI 的字串。它們可以保持單獨一行，即使超出了一行 80 個字元的限制。這使得對於給出的路徑更容易搜尋原始檔。

對所有流程控制結構使用大括號

這樣避免了else 懸掛的問題。

if (isWeekDay) {
print('Bike to work!');
} else {
print('Go dancing or read a book!');
}

有一個例外是：if 語句沒有else ，符合條件只有一行，可以省略大括號。

if (arg == null) return defaultValue;

這些典型的用於“守衛”程式碼，如果條件滿足，返回或中斷。但是它們也可以用於表示式，只要整個if 語句和表示式在同一行上。

if (parameter > limit) parameter = defaultValue;

使用 dartfmt 格式化程式碼

dartfmt 適用於下面所有規則連同其它一些微妙的啟發式規則。它比你更快並且從不出錯。如果你遵循這條規則，你可以跳過閱讀剩下的指南 。