Effective Dart - Style

간결하고 정확한 주석은 시간절약에 도움이 됩니다. 하지만 모든 주석이 도움이 되는 것은 아니고, 코드 자체만으로도 충분하도록 코드를 작성하는게 좋습니다.

Comments

DO format comments like sentences.

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

DON’T use block comments for documentation.

<good>

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

<bad>

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

Doc comments

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

Linter rule: slash_for_doc_comments

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

PREFER writing doc comments for public APIs.

Linter rule: package_api_docs, public_member_api_docs

CONSIDER writing a library-level doc comment.

• library의 용도에 대한 한 문장으로의 요약
• library 전반에서 사용되는 용어 설명
• API 사용을 알려주는 완전한 샘플 코드
• 가장 중요하거나 주로 사용되는 클래스나 함수에 대한 링크
• librar와 관련된 도메인의 외부 링크

CONSIDER writing doc comments for private APIs.

DO start doc comments with a single-sentence summary.

<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.

<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.

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

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

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

getter와 setter에 doc comments가 있는 경우 dartdoc은 setter의 doc comment를 삭제합니다.

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

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

PREFER starting library or type comments with noun phrases.

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

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

Linter rule: comment_references

/// Throws a [StateError] if ...
/// similar to [anotherMethod()], but ...
/// Similar to [Duration.inDays], but handles fractional days.
/// To create a point from polar coordinates, use [Point.polar()].

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

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

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

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

/// 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:
///
/// ```dart
/// 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:
///
/// * https://www.just-a-bare-url.com
/// * [with the URL inline](https://google.com)
/// * [or separated out][ref link]
///
/// [ref link]: https://google.com
///
/// # A Header
///
/// ## A subheader
///
/// ### A subsubheader
///
/// #### If you need this many levels of headers, you're doing it wrong

AVOID using markdown excessively.

AVOID using HTML for formatting.

PREFER backtick fences for code blocks.

<good>

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

<bad>

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

Writing

PREFER brevity.

AVOID abbreviations and acronyms unless they are obvious.

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

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

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

Reference

[Effective Dart - Documentation]