javascript - JsDoc の実際的かつ具体的な用途は何ですか?

Question

実際の現象

1. JSDoc の役割を理解するには

たとえば、このファイル: https://github.com/showdownjs...

予想される現象

自分で考えました:

1. js インターフェイスを 静的になるようにします (実際には主に 3 つ)

2. ドキュメントを便利に生成

3. IDE にとって便利であり、開発者にとってもインターフェイスを呼び出すのに便利です

それでは、実際的なメリットは何でしょうか?

Answer 1

JSDoc を書くかどうかに関係なく、JS のインターフェイスは非常に動的です。この関数は、arguments 和 call などの動的メソッドを使用してさまざまなパラメーター形式を渡すこともでき、受信側のパラメーター リストと一致しない場合もあります。

ドキュメント生成に関しては、JSDoc は確かに高速なドキュメント生成を実現します。ただし、これには、コード モジュールの編成モード、コメントの長さ、開発者のレベルに関してより高い要件があり、自動生成されたドキュメントは、通常、直接管理されているドキュメントほど読みにくくなります (たとえば、Yeoman では、ほとんどの自動生成ドキュメントを処理する場合)説明できない継承関係があります)。

開発エクスペリエンスの向上という点では、JSDoc を記述することでコード プロンプト内の IDE のインテリジェンスが向上し、eslint と連携して開発/コンパイル (パッケージ化) フェーズ中に潜在的な問題を発見することもできます。

さらに、コードをリファクタリングするときによく遭遇する質問は、[ここで実行するとき、この変数はどのような型であるべきで、この状態ではどのような値を取るべきでしょうか? 】フロントエンドとバックエンドの両方が実際にはデータを中心にプログラミングしているため、非常に動的なデータ型を使用し、ドキュメントが不足している場合、コードを保守またはリファクタリングするときに理解が困難になることがよくあります [関数は何を入力し、何を返しますか? What]、JSDoc はこれを効果的に改善できます。

しかし、質問者が本当に聞きたいのは次のようなことでしょう: [JSDoc には非常に多くの利点があるため、

私のビジネス コードでこの機能を使用する必要がありますか? 】 この質問と[単体テストを書くべきか]は、実際には同じ種類の質問です。単体テストと JSDoc を作成することには多くの利点があることは誰もが知っていますが、問題も非常に明白です。それは、コードの量が増加し、開発サイクルが長くなるということです。別のテスト ディレクトリ内の単体テスト コードとは異なり、JSDoc はビジネス コードの長さを直接増加させます (TypeScript 仕様などの新しい Doc メソッドを使用しない限り)。したがって、再利用性が高くない業務コードについては、実際には JSDoc や単体テストを書かなくても全く問題ありません（回答者は比較的小規模な工場をいくつか勤務しており、実際の業務コードは各フロントエンドで実装する必要があります）。そもそも、基本的にテーブル検索に基づいたバックエンドのポジションについては、ヌードル コードを作成する必要はありません。データを返すと、それぞれの仕様を記述するのが簡単になります。車輪を再発明して再利用可能なコード モジュールを公開する場合、完全な JSDoc と単体テストはモジュールの保守性に有益であり、ユーザーに「コードの品質が非常に優れている」と感じさせることもできます。

簡単に言うと、できるだけ早く JSDoc を開始することが重要であり、残業をしないでください。