JavaScriptコードを書くJSDocの使用

使用TypeScript 特に不必要なバグとエラーを防ぐために、きれいなコードを書くために、多くの利点を提供します.しかし、いくつかの時間と努力を学ぶには、チュートリアルやスタックオーバーの例からコピー貼り付け後のすべてのコードスニペットを適応する必要があります.私が私のように反応、ノード、急行とmongooseのためにコードを再利用するとき、かなりの挑戦.

タイプスクリプトへの代案

人気が、役に立たない、代替:全く気にしないでください.

用途eslint , しかし、それは別のものではありません.強力なタイピングの有無にかかわらず、あなたのコードをとにかくリントする必要があります.

ReactPropTypes いくつかのタイプをECMAScript/JavaScriptに反応アプリケーションで加えてください、しかし、あなたのコードをふくらませている間、proptypesは脚注だけです、彼らが最も役に立つところから遠く離れて置かれます.

そして、プロペラはありませんVanilla JS .

jsdocに入る

日本学術振興会
しばしば見落とされるかもしれないが、今まで聞いたことがない.JSDoc それがドキュメントのいくつかの短い行から利点の多くをもたらすように、より多くの注意に値する.

コードドキュメンテーション
これはJSDDocの本来の目的です.変数、関数、およびクラスの前に置かれたいくつかの行からコード/APIドキュメントを生成します.
同様のアプローチは、JavaとPHPと長い間使用されており、JSDOCは確立された実践に従って、学ぶのは非常に簡単です.

ヒントとコード補完
現代のIDEの中でJSDocを使用すると、別の利点を得るでしょう:ライブコード検査、警告、および適切なコード補完は、あなたが前に知ったことのない最も不明瞭なDOMメソッドの場合でも.または有名な古典のようなevent.currentTarget それはまだいくつかのトリッキーな落とし穴があります.
以下に例を示します.

私はモーダルダイアログをエスケープキーを入力することを許可したかった.それのような私の最初のクイックコードのようなスクリプト(ここで示されていない)はエスリントによって眉をひそめられました.☹️

きれいな、現代のバニラJSコードを書くこと
それで、私は適切で現代のコードを書くことに決めました、しかし、まだ平凡な「バニラJS」(それは、マイクロソフトのEDGEブラウザーでさえでなく、ネイティブのブラウザー支持を持たないtypescriptと違って、働くコードを生産するためにトランスポーターを必要としません)を書きました.
イベントコンテキストに依存することなく、外部から特定のモーダルダイアログを閉じることができるように、イベントと、オプションのDOM要素の2つの引数をとる関数を書きました.
JSDOCコメントを追加する前に

/**
 * close an open modal dialog
 * @param {MouseEvent} event
 * @param {HTMLElement=} elementToClose
 */
const modalClose = function modalClose(event, elementToClose) {
  // ...
};

私の読者(このコードの、そして、可能な、自動的に生成された、ドキュメンテーション/API参照)に、機能が何をするべきであるか、そして、どんな引数が予想するかについて話します:@param {MouseEvent} event今、私のIDE ( phpstorm )が役に立つ情報を教えてくれます.

私はJSDOCコメントで書く適切なタイプストリングを調べる必要さえありません!
私がタイピングを始めるとき、phpstormはコメントのこの特別な種類でさえコード補完のために若干の提案をしますMouseEvent リストの一番上にある.


JSDOC構文
基本的な構文は簡単です.
注釈ブロックはスラッシュとダブルアスタリスクで始まる特別なコメントです/**パラメータヒントは、at符号、単語“param”、およびcarly括弧の中の型定義、およびパラメータの名前に続く.
オプションのパラメータをマークするには、型の後ろに等号を付けます

@param {HTMLElement=} elementToClose

しかし、人間の読者により明確にするために、我々はまた、パラメータの名前の後ろに何かを加えることができます

@param {HTMLElement=} elementToClose (optional) DOM element to receive .closed CSS class

今、私のエディタは私のタイプ注釈を示します.そして、それは私の書かれたコードの一部でありません(彼らがtypescriptであるのと違って)しかし、むしろ暗黙的に私のコードから続きます.それで、暗黙の意味が以前より明らかである間、私の実際のコードは短くてコンパクトです.

怠惰な開発者のための支援
だけでなく、追加のヒントを参照してくださいevent: MouseEvent , しかし、我々はevent 以下のコードでは、コードの提案があり、実際に利用できるメソッドやプロパティを選択し、推奨されません.

私たちが継続するより多くの支援:ヒントとドキュメントをどこでも.私たちも訪問する必要はありませんMDN 我々のブラウザでもう!


結論
JSDocはJavaScriptのコーディングをより簡単にし、明白なエラーを回避しながらコードをコード化するのを助けてくれます.