Effective Dart: Documentation

It’s easy to think your code is obvious today without realizing how much you rely on context already in your head. People new to your code, and even your forgetful future self won’t have that context.

コードを書いているときに自分のコードが明白でわかりやすいものだと感じるのは、あなたの頭の中にその時々のコンテキストが存在するからです。

しかし、他人が初めてあなたのコードを見るとき、あるいは将来の自分が自分の書いたコードを見るとき、そのコードを書いた時のコンテキストを頼ることはできない。(他人の頭を除くことはできないし、忘れたことを思い出せるとは限らない)

 

A concise, accurate comment only takes a few seconds to write but can save one of those people hours of time.

簡潔で正確なコメントを書くのに要する時間は数秒だが、それで他者(あるいは将来の自分)の数時間の時間を節約することができる。

 

We all know code should be self-documenting and not all comments are helpful.

コード自身が自分への説明であるべきだし、すべてのコメントが有用であるとは限らない。

 

But the reality is that most of us don’t write as many comments as we should.

しかし私たちのほとんどが必要なコメントを書くことができていません。

 

It’s like exercise: you technically can do too much, but it’s a lot more likely that you’re doing too little. Try to step it up.

運動と同じで、技術的にはやりすぎることもありますが、むしろ少なすぎることの方が多いのです。ステップアップを心がけましょう。

---

Comments

The following tips apply to comments that you don’t want included in the generated documentation.

次のヒントは、生成されたドキュメントに含めたくないコメントに適用されます。

 

DO format comments like sentences.

コメントを通常の文章のように書きましょう。

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

Capitalize the first word unless it’s a case-sensitive identifier. End it with a period (or “!” or “?”, I suppose). This is true for all comments: doc comments, inline stuff, even TODOs. Even if it’s a sentence fragment.

大文字と小文字を区別する識別子でない限り、最初の単語は大文字にします。 ピリオドで終了します（または「！」または「？」と思います）。 これはすべてのコメントに当てはまります：ドキュメントコメント、インラインのもの、さらにはTODO。 文の断片であっても。

---

DON’T use block comments for documentation.

good↓

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

 

bad↓

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

You can use a block comment (/* ... */) to temporarily comment out a section of code, but all other comments should use //.

ブロックコメント (/* … */) を使ってコードの一部を一時的にコメントアウトすることができますが、他のコメントはすべて // を使用する必要があります。

---

Doc comments

docコメントは、dart docがそれを解析し、美しいdocページを生成するので、特に便利です。docコメントとは、宣言の前に表示され、dart docが探す特別な /// 構文を使用するコメントのことです。

(Flutterでのアプリ開発時に、AndroidStudioなどのIDEで、カーソルを合わせたときに表示されるコメント)

---

DO use /// doc comments to document members and types.

Using a doc comment instead of a regular comment enables dart doc to find it and generate documentation for it.

通常のコメントの代わりにドキュメントコメントを使用すると、dart docはそれを見つけて、ドキュメントを生成できます。

good↓

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

 

bad↓

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

 

For historical reasons, dart doc supports two syntaxes of doc comments: /// (“C# style”) and /** ... */(“JavaDoc style”).

歴史的な理由で、dart docは二種類のdoc commentsのシンタックスをサポートしています。

/// (“C# style”)

/** ... */(“JavaDoc style”)

We prefer /// because it’s more compact. /** and */ add two content-free lines to a multiline doc comment.

よりコンパクトになるため、私たちは///を好みます。/** と */ は、複数行の doc コメントに内容のない 2 行を必要とします。

 

If you stumble onto code that still uses the JavaDoc style, consider cleaning it up.

まだJavaDocスタイルを使用しているコードに遭遇した場合は、それをクリーンアップすることを検討してください。

---

PREFER writing doc comments for public APIs.

公開するAPIにはdoc commentsを書きましょう。

 

You don’t have to document every single library, top-level variable, type, and member, but you should document most of them.

ライブラリ、トップレベル変数、型、メンバをすべて文書化する必要はありませんが、ほとんどのものを文書化する必要があります。

---

CONSIDER writing a library-level doc comment.

ライブラリレベルのdoc commentを書くことを検討しましょう。

Unlike languages like Java where the class is the only unit of program organization, in Dart, a library is itself an entity that users work with directly, import, and think about.

クラスがプログラム編成の唯一の単位であるJavaのような言語とは異なり、Dartでは、ライブラリ自体が、ユーザーが直接操作し、インポートし、考える対象です。

 

That makes the library directive a great place for documentation that introduces the reader to the main concepts and functionality provided within. Consider including:

ライブラリは、主要なコンセプトと提供する機能を紹介する絶好の場所ですので、下記のものを含めることを検討してください。

 

• A single-sentence summary of what the library is for.

そのライブラリの概説

• Explanations of terminology used throughout the library.

ライブラリ内で使用される用語の説明

• A couple of complete code samples that walk through using the API.

APIの使い方に関してのいくつかの完全なコードサンプル

• Links to the most important or most commonly used classes and functions.

最も重要または最も一般的に使用されるクラスおよび関数へのリンク。

• Links to external references on the domain the library is concerned with.

ライブラリが関係するドメイン(領域)に関する外部参照リンク。

 

You document a library by placing a doc comment right above the library directive at the start of the file.

ファイルの先頭にあるlibraryディレクティブのすぐ上にドキュメントコメントを配置して、ライブラリをドキュメント化します。

 

If the library doesn’t have a library directive, you can add one just to hang the doc comment off of it.

ライブラリにライブラリディレクティブがない場合は、ライブラリディレクティブを追加して、ドキュメントコメントをライブラリにぶら下げることができます。

---

CONSIDER writing doc comments for private APIs.

プライベートなAPIにもdoc commentsを書くことを検討しましょう。

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の外部の利用者だけのものではありません。 また、図書館の他の部分から呼び出されるプライベートメンバーを理解するのにも役立ちます。

---

DO start doc comments with a single-sentence summary.

doc commentsは一文で始めましょう。

Start your doc comment with a brief, user-centric description ending with a period.

ドキュメントのコメントは、ピリオドで終わるユーザー中心の簡単な説明で始めます。

 

A sentence fragment is often sufficient. Provide just enough context for the reader to orient themselves and decide if they should keep reading or look elsewhere for the solution to their problem.

多くの場合、文の断片で十分です。 読者が自分自身を方向付け、読み続けるべきか、問題の解決策を他の場所で探すべきかを決定するのに十分なコンテキストを提供します。

good↓

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

 

bad↓

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

 

---

DO separate the first sentence of a doc comment into its own paragraph.

ドキュメントコメントの最初の文を独自の段落に分割してください。

Add a blank line after the first sentence to split it out into its own paragraph. If more than a single sentence of explanation is useful, put the rest in later paragraphs.

最初の文の後に空白行を追加して、それを独自の段落に分割します。 複数の説明文が役立つ場合は、残りを後の段落に入れてください。

 

This helps you write a tight first sentence that summarizes the documentation. Also, tools like dart doc use the first paragraph as a short summary in places like lists of classes and members.

これは、ドキュメントを要約する最初の文章をきっちりと書くのに役立ちます。また、dart docのようなツールでは、クラスやメンバーのリストのような場所で、最初の段落を短い要約として使用します。

good↓

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

 

bad↓

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

 

---

AVOID redundancy with the surrounding context.

周囲のコンテキストとの冗長性を避けてください。

 

The reader of a class’s doc comment can clearly see the name of the class, what interfaces it implements, etc. When reading docs for a member, the signature is right there, and the enclosing class is obvious.

クラスのドキュメントコメントの読者は、クラスの名前、実装されているインターフェイスなどを明確に確認できます。メンバーのドキュメントを読むとき、署名はすぐそこにあり、メンバーがどのクラスに属しているかは明らかです。

signature : 関数の返り値の型、引数の種類と型を示したもの

 

None of that needs to be spelled out in the doc comment. Instead, focus on explaining what the reader doesn’t already know.

既に確認できる情報はdoc commentに含める必要はありません。代わりにまだ読者に伝わっていない情報を含めましょう。

good↓

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

 

bad↓

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

If you really don’t have anything interesting to say that can’t be inferred from the declaration itself, then omit the doc comment. It’s better to say nothing than waste a reader’s time telling them something they already know.

宣言自体から推測できないような情報がない場合は、ドキュメントのコメントを省略してください。 読者がすでに知っていることを伝えて時間を無駄にするより、何も言わないほうがよいでしょう。

---

PREFER starting function or method comments with third-person verbs.

関数やメソッドのコメントは、三人称動詞で書き始めましょう。

The doc comment should focus on what the code does.

doc commentはコードが何をするのか、に焦点を当てましょう。

good↓

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

/// Starts the stopwatch if not already running.
void start() {
  ...
}

 

---

PREFER starting variable, getter, or setter comments with noun phrases.

変数・ゲッタ・セッタのコメントは名詞で書き始めましょう。

 

The doc comment should stress what the property is. This is true even for getters which may do calculation or other work. What the caller cares about is the result of that work, not the work itself.

doc commentはそのプロパティが何なのかを強調しましょう。

 

This is true even for getters which may do calculation or other work.

これは、計算やその他の作業を行う可能性のあるゲッターにも当てはまります。

 

What the caller cares about is the result of that work, not the work itself.

利用者(コメントの読者)が気にするのは、仕事自体ではなく、その仕事の結果です。

callerはゲッタを呼び出す者、そのゲッタを使う人、さらに言えばコメントを読んでいる人、ということ。

good↓

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

/// The number of checked buttons on the page.
int get checkedCount => ...

 

If a property has both a getter and a setter, then create a doc comment for only one of them. dart doc treats the getter and setter like a single field, and if both the getter and the setter have doc comments, then dart doc discards the setter’s doc comment.

プロパティにゲッターとセッターの両方がある場合は、そのうちの1つだけにドキュメントコメントを作成します。 dart docは、ゲッターとセッターを単一のフィールドのように扱い、ゲッターとセッターの両方にドキュメントコメントがある場合、dartdocはセッターのドキュメントコメントを破棄します。

---

PREFER starting library or type comments with noun phrases.

Doc comments for classes are often the most important documentation in your program.

クラスのドキュメントコメントはあなたのプログラムの中で最も重要なドキュメントである事が多いです。

 

They describe the type’s invariants, establish the terminology it uses, and provide context to the other doc comments for the class’s members.

タイプの不変条件を説明し、使用する用語を確立し、クラスのメンバーの他のドキュメントコメントにコンテキストを提供します。

 

A little extra effort here can make all of the other members simpler to document.

ここでの労力が他のメンバの説明を簡潔にすることにつながります。

good↓

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

 

---

CONSIDER including code samples in doc comments.

ドキュメントコメントの中にコードサンプルを含めることを検討してください。

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

 

---

Humans are great at generalizing from examples, so even a single code sample makes an API easier to learn.

人間はサンプルから一般化するのが得意なので、単一のコードサンプルでもAPIを習得しやすくします。

---

DO use square brackets in doc comments to refer to in-scope identifiers.

ドキュメントコメントの中でin-scopeな識別子を[ ]で囲みましょう。

If you surround things like variable, method, or type names in square brackets, then dart doc looks up the name and links to the relevant API docs. Parentheses are optional, but can make it clearer when you’re referring to a method or constructor.

変数名、メソッド名、タイプ名などを角かっこで囲むと、dartdocは名前と関連するAPIドキュメントへのリンクを検索します。 括弧はオプションですが、メソッドまたはコンストラクターを参照するときにわかりやすくすることができます。

good↓

/// Throws a [StateError] if ...
/// similar to [anotherMethod()], but ...

 

To link to a member of a specific class, use the class name and member name, separated by a dot:

特定のクラスのメンバーにリンクするには、ドットで区切ったクラス名とメンバー名を使用します。

good↓

/// Similar to [Duration.inDays], but handles fractional days.

 

The dot syntax can also be used to refer to named constructors. For the unnamed constructor, use .new after the class name:

ドット記法は名前付きコンストラクタへの参照としても使えます。名前の無いコンストラクタに関しては、クラス名の後ろに.newを使ってください。

good↓

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

 

---

DO use prose to explain parameters, return values, and exceptions.

パラメータ、戻り値、および例外を説明するために散文(普通の文章)を使用してください。

 

Other languages use verbose tags and sections to describe what the parameters and returns of a method are.

他の言語では、下記のように詳細なタグとセクションを使用して、メソッドのパラメーターと戻り値を記述します。

bad↓

/// 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) => ...

 

The convention in Dart is to integrate that into the description of the method and highlight parameters using square brackets.

下記のように、square bracketsを使用した通常の文章でコメントを書くのがDart流です。

good↓

/// 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) => ...

 

---

DO put doc comments before metadata annotations.

メタデータアノテーションの前にコメントを追加しましょう。

good↓

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

 

bad↓

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

 

---

Markdown

工事中🏗

 

 

---

Writing

We think of ourselves as programmers, but most of the characters in a source file are intended primarily for humans to read.

私たちは自分をプログラマーだと認識していますが、ソースファイル内のほとんどの文字は、主に人間が読むことを目的としています。

 

English is the language we code in to modify the brains of our coworkers. As for any programming language, it’s worth putting effort into improving your proficiency.

英語は、同僚の頭脳を修正するためにコーディングする言語です。 プログラミング言語に関しては、習熟度の向上に力を注ぐ価値があります。

 

This section lists a few guidelines for our docs. You can learn more about best practices for technical writing, in general, from articles such as Technical writing style.

このセクションでは、ドキュメントのガイドラインをいくつか示します。 テクニカルライティングのベストプラクティスについては、一般的に、テクニカルライティングスタイルなどの記事から学ぶことができます。

---

PREFER brevity.

簡潔さを優先しましょう。

 

Be clear and precise, but also terse.

明確かつ正確であるだけでなく、簡潔にします。

---

AVOID abbreviations and acronyms unless they are obvious.

明らかでない限り、略語や頭字語は避けましょう。

 

Many people don’t know what “i.e.”, “e.g.” and “et al.” mean. That acronym that you’re sure everyone in your field knows may not be as widely known as you think.

「i.e.」「e.g.」「et al.」の意味を知らない人は結構います。あなたの専門分野では誰もが知っているはずのその略語は、あなたが思っているほどには広く知られていないかもしれません。

---

PREFER using “this” instead of “the” to refer to a member’s instance.

メンバーのインスタンスを参照するには、「the」の代わりに「this」を使用しましょう。

When documenting a member for a class, you often need to refer back to the object the member is being called on. Using “the” can be ambiguous.

クラスのメンバーを文書化するとき、メンバーが呼び出されているオブジェクトを参照する必要があることがよくあります。 「the」の使用はあいまいになる可能性があります。

good↓

class Box {
  /// The value this wraps.
  Object? _value;

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

 

参考

https://dart.dev/guides/language/effective-dart/documentation