Effective Dart: 文檔

http://dart.goodev.org/guides/language/effective-dart/documentation

如果您已經知道了代碼的上下文信息,則更容易理解代碼。 但是當新手閱讀您的代碼或者很久以后您再次閱讀您的代碼, 代碼的上下文信息可能已經不記得了。編寫精煉的、準確的注釋 只需要幾秒鐘,但是以后可能節省其他人幾個小時 的時間來讀懂您的代碼。

我們已經知道代碼應該自我說明(代碼就是最好的文檔)并且并非所有的注釋都是有用的。 但是,真實情況是大家都把應該寫的評論給省略了。 和練習一樣:從技術上你可以做很多,但是實際上你 只做了一點點。嘗試著逐步提高。

  • 注釋
    • 要 按照句子的格式來格式化評論。
    • 不要 使用塊注釋作為解釋說明。
  • 文檔注釋
    • 要 使用 /// 文檔注釋來注釋成員和類型。
    • 推薦 為公開發布的 API 編寫注釋文檔。
    • 考慮 為私有 API 編寫注釋文檔。
    • 要 把第一個語句定義為一個段落。
    • 推薦 用第三人稱來開始函數或者方法的文檔注釋。
    • 推薦 使用名詞短語來開始變量、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!');
}

ERRORDEMO:

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

你可以使用塊注釋 (/ ... /) 來臨時的注釋掉一些代碼, 但是其他的所有注釋都應該使用 //。

文檔注釋

文檔注釋非常有用,dartdoc 解析這些注釋并生成 漂亮的文檔網頁 。出現在定義語句(變量定義、函數聲明、類定義 等)之前并且使用 /// 語法的都是文檔注釋。

使用 /// 文檔注釋來注釋成員和類型。

使用文檔注釋可以讓 dartdoc 來為你生成 代碼 API 文檔。

/// The number of characters in this chunk when unsplit.
int get length => ...

ERRORDEMO:

// The number of characters in this chunk when unsplit.
int get length => ...

由于歷史原因,dartdoc 支持兩種格式的文檔注釋: /// (“C# 格式”) 和 /** ... */ (“JavaDoc 格式”)。我們推薦使用 /// 是因為其更加簡潔。/***/ 在多行注釋中間添加了開頭和結尾的兩行多余 內容。 /// 在一些情況下也更加易于閱讀,例如 當注釋文檔中包含有使用 * 標記的列表內容的時候。

如果你現在還在使用 JavaDoc 風格格式,請考慮 使用新的格式。

推薦 為公開發布的 API 編寫注釋文檔。

你沒必要為所有頂級的變量、類型、成員 都提供注釋文檔,但是 對于公開的成員則應該提供注釋文檔。

考慮 為私有 API 編寫注釋文檔。

文檔不僅僅為了使用你的類的用戶所編寫。 也可以用來幫助理解你的類是如何調用其他 類的。

把第一個語句定義為一個段落。

注釋文檔中的第一個段落應該是簡潔的、面向用戶的注釋。例如下面的示例, 通常不是一個完成的語句。

/// 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) { ... }
/// Starts a new block as a child of the current chunk. Nested blocks are
/// handled using their own independent [LineWriter].
ChunkBuilder startBlock() { ... }

描述部分應該告訴讀者這個 API 可以提供哪些功能,和類似的 API 標示 其區別。不要只是 重復 API 的名字,要告訴讀者一些他們不知道的信息。

推薦 用第三人稱來開始函數或者方法的文檔注釋。

注釋應該關注于代碼 所實現的 功能。

/// 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 的注釋。

注釋文檔應該表述這個屬性是什么。雖然 getter 函數會做些計算, 但是也要求這樣,調用者關心的是其結果而 不是如何計算的。

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

/// The number of checked buttons on the page.
int get checkedCount { ... }

如果同時有 getter 和 setter,只需要在 getter 上添加注釋。 這樣 dartdoc 會按照變量來對待 getter 和 setter。

推薦 使用名詞短語來開始庫和類型注釋。

在程序中,類的注釋通常是最重要的文檔。 類的注釋描述了類型的不變性、介紹其使用的術語、 提供類成員使用的上下文信息。為類提供一些注釋可以讓 其他類成員的注釋更易于理解和編寫。

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

考慮 在文檔注釋中添加示例代碼。

/// Returns the lesser of two numbers.
///
///     min(5, 3); // 3.
num min(num a, num b) { ... }

人類非常擅長從示例中抽象出實質內容,所以即使提供 一行最簡單的示例代碼都可以讓 API 更易于理解。

使用方括號在文檔注釋中引用作用域內的標識符。

如果把變量、函數、類型名字放到方括號里面,則 dartdoc 在生成文檔的時候會鏈接到這些成員。

Throws a [StateError] if ...

similar to [anotherMethod], but ...

在標識符前面添加 new 關鍵字可以鏈接構造函數。

To create a point, call [new Point] or use [new Point.polar] to ...

使用散文的方式來描述參數、返回值以及異常信息。

其他語言使用各種標簽和額外的注釋來描述參數和 返回值。

ERRORDEMO:

/// 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 把參數、返回值等描述放到文檔注釋中,并使用方括號來引用 以及高亮這些參數和返回值。

/// 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) { ... }

避免 在注釋文檔中提供冗余的類型信息。

用戶在閱讀文檔注釋的時候可以查看類型、返回值類型以及參數類型。并且在文檔中 還可以跳轉到變量的定義地方。所以 根本沒必要在注釋中加上額外的類型信息。

要告訴讀者他們 不知道 的信息。

要 把注釋文檔放到注解之前。

/// _Deprecated: Use [newMethod] instead._
@deprecated
oldMethod();

ERRORDEMO:

@deprecated
/// _Deprecated: Use [newMethod] instead._
oldMethod();

Markdown

在注釋文檔中可以使用大部分 markdown 格式, dartdoc 會使用 markdown package 來格式化這些內容。

現在到處都有介紹 Markdown 的文檔,以及到處都是使用 Markdown。所以我們選擇了支持它。 下面是一個 Markdown 語法的快速預覽。

/// 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 /// * [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。 當你不確定的時候,就不要使用文字格式。文字格式是為了更好的表達你的意圖, 而不是替代你的文字內容。 文字內容才是最重要的。

避免 使用 HTML 來格式化文字。 在極少數情況下使用HTML 可能是 有用的。比如顯示表格。但是在大部分 情況下都沒必要使用它。和 Markdown 相比太復雜了,最好 不要使用 HTML。

如何寫注釋 雖然我們認為我們是程序員,但是大部分情況下源代碼中的內容都是為了 讓人類更易于閱讀和理解代碼。對于 任何編程語言,都值得 努力練習來提高您的熟練程度。

下面列舉了一些編寫文檔的指導原則。在 技術寫作風格 中你可以了解 技術寫作的最佳實踐。

推薦 簡潔. 要清晰和準確,同時還要簡潔。

避免 縮寫和首字母縮略詞(非常流行的除外)。 大部分人都不知道 “i.e.”、 “e.g.” 和 “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; }


所屬標簽

無標簽

官方入門指南

Flutter官方發布的入門指導,包括了如何在不同的平臺(Windows, Mac, Linux)上搭建開發環境,以及一些入門級的指導,以便您從零開始進入Flutter的世界,同時,一些Flutter的框架API,也是您開發時必不可少的工具書。

從這里進入


25选5玩法中奖