こんにちわ。いせりゅーです。
10月に入り、ようやく落ち着きを取り戻してきました。僕は23卒のエンジニアで入社して半年が経ちました。早いですね💦
業務中にレビューを受けた際、いくつか非常に参考になるアドバイスを得ることができました。その内容を共有し、皆さんと一緒に学んでいきたいと思います。
問題の背景
- コメントアウトについて考えずに記載をしていた。
- １行コメント、複数行コメント、ドキュメントコメントの存在は知っていたが、それぞれの役割を正確に理解していなかった。
コメントの種類
Dartの公式サイトから引用しています。
認識のミスがありましたら、コメントいただけると幸いです🙇
コメントには3つの種類があります
- １行コメント
- 複数行コメント
- ドキュメントコメント
１行コメント(Single-line comments)
- 行の先頭に
//をつけることで、その行のコメントとして扱われる。
記載例
void main() {
// TODO: refactor into an AbstractLlamaGreetingFactory?
print('Welcome to my Llama farm!');
}
複数行コメント(Multi-line comments)
-
/*で始めて*/で終わる。この間に記述された内容は、ドキュメントコメントでなければDartのコンパイラによって無視される。
記載例
void main() {
/*
* This is a lot of work. Consider raising chickens.
Llama larry = Llama();
larry.feed();
larry.exercise();
larry.clean();
*/
}
ドキュメントコメント(Documentation comments)
-
/**または///で始まる単行または複行のコメントである。ドキュメンテーション・コメントの内側では、Dartのコンパイラはそれが括弧で囲まれていない限り総てのテキストを無視する。 - ドキュメントとして生成される。
個人的には「ドキュメントとして生成される」点がとても驚きました❗️❗️
実際にどうなっているのか見てみましょう。
具体例として、Riverpodのコードを用いました。（一部抜粋）
詳しくは下のリンク↓
記載例
riverpod/packages/riverpod/lib/src/common.dart
/// A utility for safely manipulating asynchronous data.
///
/// By using [AsyncValue], you are guaranteed that you cannot forget to
/// handle the loading/error state of an asynchronous operation.
///
/// It also exposes some utilities to nicely convert an [AsyncValue] to
/// a different object.
/// For example, a Flutter Widget may use [when] to convert an [AsyncValue]
/// into either a progress indicator, an error screen, or to show the data:
///
/// ```dart
/// /// A provider that asynchronously exposes the current user
/// final userProvider = StreamProvider<User>((_) async* {
/// // fetch the user
/// });
///
/// class Example extends ConsumerWidget {
/// @override
/// Widget build(BuildContext context, WidgetRef ref) {
/// final AsyncValue<User> user = ref.watch(userProvider);
///
/// return user.when(
/// loading: () => CircularProgressIndicator(),
/// error: (error, stack) => Text('Oops, something unexpected happened'),
/// data: (user) => Text('Hello ${user.name}'),
/// );
/// }
/// }
/// ```
Riverpodのドキュメントを確認してみると、以下の記載がありました。
リンクはこちらになります。
ちなみにドキュメントの作成方法としては、
１、プロジェクトに移動
cd (プロジェクト)
２、生成する
dart pub get
dart doc .
警告
ドキュメントを生成するには、最初にdart pub getを実行する必要があリます。
また、dart analyzeでエラーが出ないようにする必要もあります。
生成場所としては、doc/apiの中に生成されます。HTML形式で生成されるため、気になる方は実際に見てみると面白いと思います。
最後に
今までドキュメントコメントなどは全く考えていませんでした。入社して半年でこの事実を知れて、アウトプットできたことはとてもいいメリットになっていくと信じています。
これからももりもりとインプットとアウトプットを頑張っていきます🤗
もし、何かありましたらお気軽にご連絡ください🙇
参考文献