Flutter學習之Dart語言註釋

代碼註釋是開發過程當中必不可少的一個過程，那麼，咱們在進行Flutter開發時，怎麼去進行文檔註釋呢？ 這篇文章的主旨就是Flutter所使用的dart語言註釋學習。

Dart支持單行註釋, 多行註釋和文檔註釋

1.單行註釋

單行註釋以//開頭， Dart編譯器會忽略//和行尾之間的全部內容

say() {
    // TODO: say something
    print('Hello dart!');
  }
複製代碼

2.多行註釋

多行註釋以 /* 開頭，以 / 結尾, Dart編譯器忽略 / 和 */ 之間的全部內容（除非註釋是文檔註釋）, 多行註釋能夠嵌套

sayWhat(String what) {
    /* * Say something * */
    print(what);
  }
複製代碼

3.文檔註釋

文檔註釋是以 ///或 /** 開頭的多行或單行註釋, 在連續行上使用 /// 與多行文檔註釋具備相同的效果。

在文檔註釋中，Dart編譯器忽略全部文本，除非它括在括號中。 使用括號，您能夠引用類，方法，字段，頂級變量，函數和參數。 括號中的名稱在已記錄的程序元素的詞法範圍內獲得解析。

/// Dart class
///
/// TODO: Say hello to dart
class Dart {
  /// Say hello to dart
  say() {
    // TODO: say something
    print('Hello dart!');
  }

  /// Say something to dart
  /// The string [what] is what you want to say.
  sayWhat(String what) {
    /* * Say something * */
    print(what);
  }
}
複製代碼

Windows10+Flutter環境下咱們使用dart sdk的文檔生成工具來生成文檔(dartdoc的Github地址)，dartdoc.bat位於

XXX\dart-sdk\bin
複製代碼

從Flutter項目的根目錄運行dartdoc, 文檔目錄會根據flutter項目的目錄的lib下進行生成

咱們能夠看到生成的文檔放在了目錄

項目目錄\doc\api 
複製代碼

用瀏覽器打開自定義類的註解爲

4.高效Dart註釋

• 註釋
• 文檔註釋
• Markdown
• 寫註釋

在編寫代碼時， 很容易認爲本身的代碼已經寫得很清楚，可是沒有意識到已經依賴腦海中的上下文，若是另外一我的接手你的代碼的話，或者代碼寫完一段時間後再回顧的話，一段簡明扼要的註釋是很是重要的，能夠節省大量時間，所以下面這裏有一些提升dart開發的註釋竅門。

• 註釋

  註釋句子化

  避免使用塊註釋

• 文檔註釋

  使用 /// 註釋成員和類型

  優先爲public的接口編寫註釋

  考慮寫一個庫級別的文檔註釋

  考慮爲private的接口編寫文檔註釋

  文檔開頭儘可能用單句總結

  分離文檔註釋的第一句到本身的段落中

  避免與周圍上下文冗餘

  優先使用第三人稱動詞註釋函數或方法

  優先使用名詞短語註釋變量, getter或setter

  優先使用名詞短語註釋庫或者類型

  考慮使用代碼示例註釋

  儘可能在文檔註釋中使用方括號來引用範圍內標識符

  儘可能簡約地註釋參數, 返回值和異常

  儘可能在元數據註釋以前加上文檔註釋

• Markdown 避免過分使用markdown

  避免使用HTML進行格式化

  優先使用反括號來隔開代碼塊

• 寫註釋 簡短優先

  避免使用縮寫詞和縮寫詞

  首選使用「this」而不是「the」來引用成員實例

註釋

如下提示適用於你不但願包含在生成的文檔中的註釋

註釋句子化

// Not if there is nothing before it.
if (_chunks.isEmpty) return false;
複製代碼

針對英文：第一個字母需大寫，除非它是區分大小寫的標識符， 且須要使用句號，或者！或者？結束句子，全部註釋都需如此：文檔註釋，內聯內容，甚至是TODO。

中文： 儘可能用一句簡明扼要的話註釋

避免使用塊註釋

greet(name) {
  // Assume we have a valid name.
  print('Hi, $name!');
}
複製代碼

下面爲不推薦示範：

greet(name) {
  /* Assume we have a valid name. */
  print('Hi, $name!');
}
複製代碼

推薦使用（/ * ... * /）註釋代碼，其餘文字註釋應該使用//

文檔註釋

文檔註釋特別方便，由於dartdoc命令能夠解析並生成好看的文檔頁。文檔註釋是任何出如今聲明以前的註釋，dartdoc會查找使用 /// 標記的註釋

使用 /// 註釋成員和類型

Linter規則：slash_for_doc_comments 使用文檔註釋 /// 而不是常規的註釋使執行dartdoc命令時能找到註釋並生成文檔，通常在方法和類名上註釋

/// 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支持doc comments的兩種語法：///（「C＃style」）和/ ** ... * /（「JavaDoc style」），咱們更喜歡///，由於它更緊湊。 / *和 /將兩條無內容行添加到多行文檔註釋中。 在某些狀況下，///語法也更容易閱讀，例如當doc註釋包含使用*標記列表項的項目符號列表時。

若是您偶然發現仍使用JavaDoc樣式的代碼，請考慮清理它。

優先爲public的接口編寫註釋

Linter 規則: package_api_docs, public_member_api_docs

沒必要記錄每一個庫，頂級變量，類型和成員，但應該註釋其中的大多數。

考慮寫一個庫級別的文檔註釋

與Java這樣的語言不一樣，類是程序組織中的惟一單元，可是在Dart中，庫自己就是用戶直接使用，導入和思考的實體。 這使得庫指令成爲文檔註釋的好地方，能夠向讀者介紹其中提供的主要概念和功能。 考慮包括：

• 關於庫用途的單句摘要。
• 整個庫使用的術語解釋。
• 一些使用API完成的完整代碼示例。
• 連接到(即庫中使用的)最重要或最經常使用的類和函數。
• 連接到(即庫中使用的)庫所關注的域上的外部引用。

你能夠經過在文件開頭的庫指令上方放置doc註釋來記錄庫。 若是庫沒有庫指令，您能夠添加一個只是掛起文檔註釋。

考慮爲private的接口編寫文檔註釋

Doc comments aren’t just for external consumers of your library’s public API. They can also be helpful for understanding private members that are called from other parts of the library.

文檔註釋不只適用於庫的公共API， 一樣有助於理解從庫的其餘部分調用的私有成員。

文檔開頭儘可能用單句總結

開始以句號結尾的簡短的，以用戶爲中心的註釋文檔。 句子片斷一般就足夠了，爲讀者提供足夠的上下文來定位本身，並決定是否應該繼續閱讀或尋找解決問題的方法。

/// Deletes the file at [path] from the file system.
void delete(String path) {
  ...
}
複製代碼

下面爲不推薦示範：

/// Depending on the state of the file system and the user's permissions, /// certain operations may or may not be possible. If there is no file at /// [path] or it can't be accessed, this function throws either [IOError]
/// or [PermissionError], respectively. Otherwise, this deletes the file.
void delete(String path) {
  ...
}
複製代碼

簡而言之就是儘可能簡明扼要

分離文檔註釋的第一句到本身的段落中

在第一句以後添加一個空行，將其拆分爲本身的段落。 若是多於一句解釋是有用的，請將其他部分放在後面的段落中。 這有助於您編寫一個簡短的第一句話來總結文檔。 此外，像Dartdoc這樣的工具使用第一段做爲類和列表列表等地方的簡短摘要。

/// Deletes the file at [path].
///
/// Throws an [IOError] if the file could not be found. Throws a
/// [PermissionError] if the file is present but could not be deleted.
void delete(String path) {
  ...
}
複製代碼

下面爲不推薦示範：

/// Deletes the file at [path]. Throws an [IOError] if the file could not
/// be found. Throws a [PermissionError] if the file is present but could
/// not be deleted.
void delete(String path) {
 ...
}
複製代碼

簡而言之即第一行說明該方法或類的主要功能，而後空一行，在進行詳細描述或者參數等解釋

避免與周圍上下文冗餘

讀者能夠從文檔註釋中清楚地看到類的名稱，它實現的接口等。當讀到成員的文檔註釋時，簽名就在那裏，而封閉的類是顯而易見的。 這些都不須要在文檔註釋中拼寫出來。 相反，專一於解釋讀者不知道的內容。

class RadioButtonWidget extends Widget {
 /// Sets the tooltip to [lines], which should have been word wrapped using
 /// the current font.
 void tooltip(List<String> lines) {
   ...
 }
}
複製代碼

下面爲不推薦示範：

class RadioButtonWidget extends Widget {
  /// Sets the tooltip for this radio button widget to the list of strings in
  /// [lines].
  void tooltip(List<String> lines) {
    ...
  }
}
複製代碼

上面第一段註釋清除地說明了該函數的使用目的，而下面不推薦的示例，則與上下文冗餘了，"for this radio button widget"。

優先使用第三人稱動詞註釋函數或方法

文檔註釋應該關注代碼的做用

/// Returns `true` if every element satisfies the [predicate].
bool all(bool predicate(T element)) => ...

/// Starts the stopwatch if not already running.
void start() {
  ...
}
複製代碼

優先使用名詞短語註釋變量, getter或setter

文檔註釋應該強調屬性是什麼， 即便對於可能進行計算或其餘工做的也是如此。 讀者應該關心的是這段代碼的結果，而不是代碼自己。

/// The current day of the week, where `0` is Sunday.
int weekday;

/// The number of checked buttons on the page.
int get checkedCount => ...
複製代碼

優先使用名詞短語註釋庫或者類型

類的文檔註釋一般是程序中最重要的部分，它們描述了類型的不變性，創建了它使用的術語，併爲類的成員提供了其餘文檔註釋的上下文，在這裏作一點額外的努力可讓其餘成員更容易記錄

/// A chunk of non-breaking output text terminated by a hard or soft newline.
///
/// ...
class Chunk { ... }
複製代碼

簡而言之就是多用專業術語，讓註釋看起來高大上

考慮使用代碼示例註釋

/// Returns the lesser of two numbers.
///
/// ```dart
/// min(5, 3) == 3
/// ```
num min(num a, num b) => ...
複製代碼

人類很是善於從示例中進行歸納，所以即便是單個代碼示例也可使API更容易學習

######儘可能在文檔註釋中使用方括號來引用範圍內標識符。 Linter規則: comment_references 若是在方括號中包含變量，方法或類型名稱等內容，則dartdoc會查找名稱並連接到相關的API文檔。 括號是可選的，但在引用方法或構造函數時可使它更清晰

/// Throws a [StateError] if ...
/// similar to [anotherMethod()], but ...
複製代碼

要連接到特定類的成員，請使用以點分隔的類名和成員名：

/// Similar to [Duration.inDays], but handles fractional days.
複製代碼

點語法也可用於引用命名構造函數。 對於未命名的構造函數，在類名後面加上括號：

/// To create a point, call [Point()] or use [Point.polar()] to ...
複製代碼

儘可能簡約地註釋參數, 返回值和異常

Dart中的約定是將其集成到方法的描述中，並使用方括號突出顯示參數:

/// 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) => ...
複製代碼

下面爲不推薦示範： 其餘語言使用詳細標記和部分來描述方法的參數和返回值。

/// 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) => ...
複製代碼

好吧，做爲一個常年使用java開發的中國Androider, 我更偏向於使用第二種方式

儘可能在元數據註釋以前加上文檔註釋

/// A button that can be flipped on and off.
@Component(selector: 'toggle')
class ToggleComponent {}
複製代碼

下面爲不推薦示範：

@Component(selector: 'toggle')
/// A button that can be flipped on and off.
class ToggleComponent {}
複製代碼

這裏我不說話，讓你本身看

Markdown

你能夠在文檔註釋中使用大多數markdown格式，dartdoc將使用markdown包相應地處理它。 下面爲一個使用示例

/// This is a paragraph of regular text.
///
/// This sentence has *two* _emphasized_ words (italics) and **two**
/// __strong__ ones (bold).
///
/// A blank line creates a 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 fenced in triple backticks: /// /// ``` /// this.code /// .will /// .retain(its, formatting); /// ``` /// /// The code language (for syntax highlighting) defaults to Dart. You can /// specify it by putting the name of the language after the opening backticks: /// /// ```html /// <h1>HTML is magical!</h1> /// ``` /// /// 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
複製代碼

能夠看到使用了不少markdown語法註釋

避免過分使用markdown

若有疑問，請格式化。 存在格式化以闡明您的內容，而不是替換它。 words很重要

避免使用HTML進行格式化

在極少數狀況下使用它可能頗有用，例如表格，但在幾乎全部狀況下，若是它在Markdown中過於複雜，你最好不要表達它。

優先使用反括號來隔開代碼塊

Markdown有兩種表示代碼塊的方法：在每行上壓縮代碼四個空格，或者用反引號code表示。 當在縮進已經有意義的Markdown列表或代碼塊自己包含縮進代碼的內容中使用時，前一種語法很脆弱，意思就是使用markdown註釋時，前面已經使用了縮進，可是如今再使用縮進表示代碼的話，會顯得很差閱讀

反引號語法避免了那些縮進問題，讓您指出代碼的語言，而且與使用內聯代碼的反引號一致。

/// You can use [CodeBlockExample] like this:
///
/// ```
/// var example = CodeBlockExample();
/// print(example.isItGreat); // "Yes."
/// ```
複製代碼

下面爲不推薦示範：

/// You can use [CodeBlockExample] like this:
///
///     var example = CodeBlockExample();
///     print(example.isItGreat); // "Yes."
複製代碼

這裏總結一下什麼狀況使用markdown註釋比較好： 1.註釋類時，該類功能須要目錄說明 2.示例代碼比較多的時候 3.須要列表說明功能的時候

寫註釋

在開始寫註釋的時候，不管咱們使用的是中文仍是英文，我以爲都得有一個寫註釋的習慣，由於這關係到之後的我的代碼回顧，和別人閱讀你的代碼的時候的難易程度。

簡短優先

要清晰準確，但也要簡潔。

避免使用縮寫詞和縮寫詞

對於英文來講：許多人不知道「ie」，「eg」和「et al」是什麼意思，你確信你所在領域的每一個人都知道這個首字母縮略詞可能並不像你想象的那麼廣爲人知

對於中文來講：我的以爲縮寫詞應該會用得比較少

首選使用「this」而不是「the」來引用成員實例

記錄類的成員時，一般須要返回調用該成員的對象，使用「the」可能含糊不清

class Box {
  /// The value this wraps.
  var _value;

  /// True if this box contains a value.
  bool get hasValue => _value != null;
}
複製代碼

Dart語言之旅：www.dartlang.org/guides/lang…