一、注釋（非文檔注釋）
- 要按照句子的格式來(lái)格式化評(píng)論。
// Not if there is nothing before it.
if (_chunks.isEmpty) return false;
如果第一個(gè)單詞不是大小寫(xiě)相關(guān)的標(biāo)識(shí)符，則首字母要大寫(xiě)。使用標(biāo)點(diǎn)符號(hào)結(jié)尾 （句號(hào)、感嘆號(hào)、問(wèn)號(hào)）。對(duì)于所有的注釋都是這樣要求的：文檔注釋、 行內(nèi)注釋、甚至 TODO 注釋。即使是一句話的一半也需要如此。
- 不要 使用塊注釋作為解釋說(shuō)明。
greet(name) { // 推薦
// Assume we have a valid name.
print('Hi, $name!');
}
greet(name) { // 不建議
/* Assume we have a valid name. */
print('Hi, $name!');
}
你可以使用塊注釋 (/* ... */) 來(lái)臨時(shí)的注釋掉一些代碼， 但是其他的所有注釋都應(yīng)該使用 //。
二、文檔注釋
文檔注釋非常有用，dartdoc 解析這些注釋并生成 漂亮的文檔網(wǎng)頁(yè) 。出現(xiàn)在定義語(yǔ)句（變量定義、函數(shù)聲明、類定義 等）之前并且使用 /// 語(yǔ)法的都是文檔注釋。
2.1.要使用///文檔注釋來(lái)注釋成員和類型。
使用文檔注釋可以讓 dartdoc 來(lái)為你生成 代碼 API 文檔。
/// The number of characters in this chunk when unsplit.(好的范例)
int get length => ...
// The number of characters in this chunk when unsplit.（壞的范例）
int get length => ...
由于歷史原因，dartdoc 支持兩種格式的文檔注釋： /// (“C# 格式”) 和 /** ... */ (“JavaDoc 格式”)。我們推薦使用 /// 是因?yàn)槠涓雍?jiǎn)潔。/** 和 */ 在多行注釋中間添加了開(kāi)頭和結(jié)尾的兩行多余 內(nèi)容。 /// 在一些情況下也更加易于閱讀，例如 當(dāng)注釋文檔中包含有使用 * 標(biāo)記的列表內(nèi)容的時(shí)候。
如果你現(xiàn)在還在使用 JavaDoc 風(fēng)格格式，請(qǐng)考慮 使用新的格式。
2.2.要把第一個(gè)語(yǔ)句定義為一個(gè)段落。
注釋文檔中的第一個(gè)段落應(yīng)該是簡(jiǎn)潔的、面向用戶的注釋。
/// Defines a flag.
///
/// Throws an [ArgumentError] if there is already an option named [name] or
/// there is already an option using abbreviation [abbr]. Returns the new flag.
Flag addFlag(String name, String abbr) { ... }
描述部分應(yīng)該告訴讀者這個(gè) API 可以提供哪些功能，和類似的 API 標(biāo)示 其區(qū)別。不要只是 重復(fù) API 的名字，要告訴讀者一些他們不知道的信息。
2.3.推薦用第三人稱來(lái)開(kāi)始函數(shù)或者方法的文檔注釋。
注釋?xiě)?yīng)該關(guān)注于代碼 所實(shí)現(xiàn)的 功能。
/// Returns `true` if every element satisfies the [predicate].
bool all(bool predicate(T element)) { ... }
/// Starts the stopwatch if not already running.
void start() { ... }
2.4.推薦使用名詞短語(yǔ)來(lái)開(kāi)始變量、getter、setter 的注釋。
注釋文檔應(yīng)該表述這個(gè)屬性是什么。雖然 getter 函數(shù)會(huì)做些計(jì)算， 但是也要求這樣，調(diào)用者關(guān)心的是其結(jié)果而 不是如何計(jì)算的。
/// The current day of the week, where `0` is Sunday.
int weekday;
/// The number of checked buttons on the page.
int get checkedCount { ... }
如果同時(shí)有 getter 和 setter，只需要在 getter 上添加注釋。 這樣 dartdoc 會(huì)按照變量來(lái)對(duì)待 getter 和 setter。
2.5.推薦使用名詞短語(yǔ)來(lái)開(kāi)始庫(kù)和類型注釋。
在程序中，類的注釋通常是最重要的文檔。 類的注釋描述了類型的不變性、介紹其使用的術(shù)語(yǔ)、 提供類成員使用的上下文信息。為類提供一些注釋可以讓 其他類成員的注釋更易于理解和編寫(xiě)。
/// A chunk of non-breaking output text terminated by a hard or soft newline.
///
/// ...
class Chunk { ... }
2.6.考慮在文檔注釋中添加示例代碼。
/// Returns the lesser of two numbers.
///
/// min(5, 3); // 3.
num min(num a, num b) { ... }
人類非常擅長(zhǎng)從示例中抽象出實(shí)質(zhì)內(nèi)容，所以即使提供 一行最簡(jiǎn)單的示例代碼都可以讓 API 更易于理解。
2.7.要使用方括號(hào)在文檔注釋中引用作用域內(nèi)的標(biāo)識(shí)符。
如果把變量、函數(shù)、類型名字放到方括號(hào)里面，則 dartdoc 在生成文檔的時(shí)候會(huì)鏈接到這些成員。
Throws a [StateError] if ...
similar to [anotherMethod], but ...
在標(biāo)識(shí)符前面添加 new 關(guān)鍵字可以鏈接構(gòu)造函數(shù)。
To create a point, call [new Point] or use [new Point.polar] to ...
2.8.要使用散文的方式來(lái)描述參數(shù)、返回值以及異常信息。
其他語(yǔ)言使用各種標(biāo)簽和額外的注釋來(lái)描述參數(shù)和 返回值。
壞的范例：
/// Defines a flag with the given name and abbreviation.
///
/// @param name The name of the flag.
/// @param abbr The abbreviation for the flag.
/// @returns The new flag.
/// @throws ArgumentError If there is already an option with
/// the given name or abbreviation.
Flag addFlag(String name, String abbr) { ... }
而 Dart 把參數(shù)、返回值等描述放到文檔注釋中，并使用方括號(hào)來(lái)引用 以及高亮這些參數(shù)和返回值(好的范例)。
/// Defines a flag.
///
/// Throws an [ArgumentError] if there is already an option named [name] or
/// there is already an option using abbreviation [abbr]. Returns the new flag.
Flag addFlag(String name, String abbr) { ... }
2.9.避免在注釋文檔中提供冗余的類型信息。
用戶在閱讀文檔注釋的時(shí)候可以查看類型、返回值類型以及參數(shù)類型。并且在文檔中 還可以跳轉(zhuǎn)到變量的定義地方。所以 根本沒(méi)必要在注釋中加上額外的類型信息。
要告訴讀者他們 不知道 的信息。
2.10.要把注釋文檔放到注解之前。
/// _Deprecated: Use [newMethod] instead._
@deprecated
oldMethod();
注意：
1、推薦為公開(kāi)發(fā)布的 API 編寫(xiě)注釋文檔：
你沒(méi)必要為所有頂級(jí)的變量、類型、成員 都提供注釋文檔，但是 對(duì)于公開(kāi)的成員則應(yīng)該提供注釋文檔。
2、考慮為私有 API 編寫(xiě)注釋文檔：
文檔不僅僅為了使用你的類的用戶所編寫(xiě)。 也可以用來(lái)幫助理解你的類是如何調(diào)用其他 類的。
三、Markdown
在注釋文檔中可以使用大部分 markdown 格式， dartdoc 會(huì)使用 markdown package 來(lái)格式化這些內(nèi)容。
現(xiàn)在到處都有介紹 Markdown 的文檔，以及到處都是使用 Markdown。所以我們選擇了支持它。 下面是一個(gè) Markdown 語(yǔ)法的快速預(yù)覽。
/// This is a paragraph of regular text.
///
/// This sentence has *two* _emphasized_ words (i.e. italics) and **two**
/// __strong__ ones (bold).
///
/// A blank line creates another separate paragraph. It has some `inline code`
/// delimited using backticks.
///
/// * Unordered lists.
/// * Look like ASCII bullet lists.
/// * You can also use `-` or `+`.
///
/// 1. Numbered lists.
/// 2. Are, well, numbered.
/// 1. But the values don't matter.
///
/// * You can nest lists too.
/// * They must be indented at least 4 spaces.
/// * (Well, 5 including the space after `///`.)
///
/// Code blocks are indented the same way:
///
/// this.code
/// .will
/// .retain(its, formatting);
///
/// Links can be:
///
/// * http://www.just-a-bare-url.com
/// * [with the URL inline](http://google.com)
/// * [or separated out][ref link]
///
/// [ref link]: http://google.com
///
/// # A Header
///
/// ## A subheader
///
/// ### A subsubheader
///
/// #### If you need this many levels of headers, you're doing it wrong
3.1.避免過(guò)度使用 markdown。
當(dāng)你不確定的時(shí)候，就不要使用文字格式。文字格式是為了更好的表達(dá)你的意圖， 而不是替代你的文字內(nèi)容。 文字內(nèi)容才是最重要的。
3.2.避免使用 HTML 來(lái)格式化文字。
在極少數(shù)情況下使用HTML 可能是 有用的。比如顯示表格。但是在大部分 情況下都沒(méi)必要使用它。和 Markdown 相比太復(fù)雜了，最好 不要使用 HTML。
四、如何寫(xiě)注釋
雖然我們認(rèn)為我們是程序員，但是大部分情況下源代碼中的內(nèi)容都是為了 讓人類更易于閱讀和理解代碼。對(duì)于 任何編程語(yǔ)言，都值得 努力練習(xí)來(lái)提高您的熟練程度。
下面列舉了一些編寫(xiě)文檔的指導(dǎo)原則。在 技術(shù)寫(xiě)作風(fēng)格 中你可以了解 技術(shù)寫(xiě)作的最佳實(shí)踐。
4.1. 推薦 簡(jiǎn)潔.
要清晰和準(zhǔn)確，同時(shí)還要簡(jiǎn)潔。
4.2.避免縮寫(xiě)和首字母縮略詞（非常流行的除外）。
大部分人都不知道 “i.e.”、 “e.g.” 和 “et. al.” 的意思。你所在領(lǐng)域的 首字母縮略詞對(duì)于其他人可能并不了解。
4.3.推薦使用 “this” 而不是 “the” 來(lái)引用實(shí)例成員。
當(dāng)提及到類的成員，通常是指被調(diào)用的對(duì)象實(shí)例的成員。 使用 “the” 可能會(huì)導(dǎo)致混淆。
class Box {
/// The value this wraps.
var _value;
/// True if this box contains a value.
bool get hasValue => _value != null;
}
參考資料：
Effective Dart
