在 Dart 中使用 setter 和 getter 记录变量的约定是什么？答案

【问题标题】：What is the convention for documenting variables with setters and getters in Dart?在 Dart 中使用 setter 和 getter 记录变量的约定是什么？
【发布时间】：2021-05-15 13:20:48
【问题描述】：

考虑以下示例（如果您使用提供程序 Flutter 包，则很常见）：您有一个带有私有变量的类，该变量可以通过 setter 和 getter 访问。记录此内容的约定/推荐方式是什么？

class Foo extends ChangeNotifier {

  int _bar = 0;

  int get bar => bar;

  set bar(int bar){
    _bar = bar;
    notifyListeners();
  }
}

您应该在 setter 和 getter 中都添加 doc cmets 并解释变量在两个 cmets 中的用途，还是应该只在私有变量中添加 doc 注释？

例如：

class Foo extends ChangeNotifier {

  /// The number of bars in the foo.
  int _bar = 0;

  /// Get the number of bars in the foo.
  int get bar => bar;

  /// Set the number of bars in the foo.
  set bar(int bar){
    _bar = bar;
    notifyListeners();
  }
}

对比

class Foo extends ChangeNotifier {

  /// The number of bars in the foo.
  int _bar = 0;

  int get bar => _bar;

  set bar(int bar){
    _bar = bar;
    notifyListeners();
  }
}

第一个例子是最清楚的，但它可能意味着很多重复的 cmets。第二个示例减少了 cmets 的数量，但并不那么容易看到 getter / setter 的作用（例如，在 vs 代码中将鼠标悬停在它上面）。 Dart 团队是否有建议或约定在这种情况下应如何编写文档？

【问题讨论】：

我会做第一个例子，因为 DartDoc 似乎结合了给定属性的 set 和 get 的文档。一个例子是List 上的length：api.dart.dev/stable/2.13.0/dart-core/List/length.html
所以，dartdoc 似乎没有为私有变量生成文档（当你考虑它时是合理的）。所以，就像你说的，最好的方法可能是记录 getter 和 setter 而不是私有变量。也许只是用常规的// 评论来评论？
如果私有变量的作用不明显，是的，您应该记录它。但除此之外，我会说记录界面的公共部分就足够了。

标签： dart code-documentation

【解决方案1】：

文档，传统上是吸气剂。使用名词短语，像记录字段一样记录它。然后 DartDoc 工具会将其显示为一个字段。 https://dart.dev/guides/language/effective-dart/documentation#prefer-starting-variable-getter-or-setter-comments-with-noun-phrases

【讨论】：