Blog

JSDoc で JavaScript のコメントを書こう

2017.06.13Cat:javascript デザイナー

複数の人で開発を進める場合や、プログラムの規模が大きくなってきた場合に、
コメントの記述が、開発の大きな助けとなります。
さらにそのコメントが、標準化された方法で記述されていると、さらに可読性が高まり、
生産性の向上が期待できます。

私はこれまで、特にそういったことを気にせずにコメントを書いたり書かなかったりしてきましたが、
規模の大きな開発に関わるときに、このことが障害になってしまうことを感じ、
コメントの記述を見直そうと思い調べてみました。

今回紹介するのは、現在、最もポピュラーと思われる JSDoc コメントというコメントの記述方法です。
JSDoc コメントは、Google の JavaScript スタイルガイド でも推奨されているコメントの方法で、
AngularJS、CreateJS、jQuery(部分的に) など、メジャーなライブラリで利用されています。

 

JSDoc のメリット

  • プログラムの可読性が高まり、複数の人が関わる開発や、規模が大きなプログラムでの生産効率が高まる
  • JavaScript で曖昧になりがちな変数の型やオブジェクトの種類(配列、関数、コンストラクタ、クラスなど)が明確になり、予期しないバグの防止につながる
  • JSDoc に対応したエディタを使うことで、コーディングの補完が強化される

デメリット

  • コードが長くなるので、開発用とminifyした読み込み用のファイルに分ける必要がある
  • コメント記述のための手間と時間が必要になる

もちろん手間がかかるなどのデメリットもありますが、長い目で見れば、メリットのほうが大きいと考えられます。

 

基本的な記述方法 (Google JavaScript Style Guide を参照)

  • “/**” + 「改行」 でスタート
  • 途中は「半角スペース」 + “*” + 「半角スペース」記述
  • 終わりは「半角スペース」 + “*/”

説明が長く、改行が必要な場合は、4つの半角スペースを文章の前に追加

 

よく使うであろう記述の例

変数

配列

連想配列

より詳細に説明する場合は

関数

クラス(プロトタイプ)

 

このように、JSDoc の記述は決して軽いものではないので、コードエディタの補完機能と合わせることをオススメいたします。

Atom を使っている方なら、このプラグインが便利

docblockr

関数や変数の直前で、 /** の後改行することで、DocJSのベースを自動で保管してくれます。

atom-ternjs

JavaScript を解析して補完してくれるプラグインですが、
JSDoc と合わせることで、補完時に関数の引数の型などを確認することができます。

参考サイト

メリット

JavaScriptでJSDocコメントを書くメリットとは – ICS MEDIA

ガイド

JSDocコメント – Google JavaScript スタイルガイド – 日本語訳 – アットウィキ

Google JavaScript Style Guide

Atom プラグイン

AtomでPHPやJavaScriptのDocコメントを書くのにdocblockrがめっちゃ便利 | PengNote

JavaScriptのコード補完できていますか? – Aqutras Members’ Blog

Author Profile

ninomiya
ninomiya
Webデザイナー兼コーダーです。 イラストを描くのも好きです。 SVGとCanvasを使ったWEBアプリにも興味があります。 よろしくお願いいたします。
» 投稿一覧
  • Launch Cart次世代ECサイト構築システム 初期月額無料
  • LaunchMovie ECに特化した動画制作サービス

Archive

ページTOPへ