Lesson 3 コメント ― Python基礎文法入門、APIリファレンスの使い方：機械学習＆ディープラーニング入門（Python編）
Python言語の文法を、コードを書く流れに沿って説明していく連載。今回は、コードの中で頻繁に使われるコメント機能を説明。さらに、コーディング作業で常用するAPIリファレンスの使い方について紹介する。
この記事は会員限定です。会員登録（無料）すると全てご覧いただけます。
ご注意：本記事は、＠IT／Deep Insider編集部（デジタルアドバンテージ社）が「deepinsider.jp」というサイトから、内容を改変することなく、そのまま「＠IT」へと転載したものです。このため用字用語の統一ルールなどは＠ITのそれとは一致しません。あらかじめご了承ください。
前回は「モジュール」について説明した。今回は、参考説明などをコード内に記述するための「コメント」機能について説明し、さらにPythonのコードを記述する際に参考になるヘルプドキュメント「APIリファレンス」を紹介する。※脚注や図、コードリストの番号は前回からの続き番号としている。
なお本連載は、実際にライブラリ「TensorFlow」でディープラーニングのコードを書く流れに沿って、基礎文法が学んでいけるように目次を構成している。よって本来であれば、Lesson 1で掲載した図1-aのサンプルコードの3行目以降の説明に入るはずだが、今回はその原則から外れて、Lesson 1で掲載した図1-d（下に再掲）にあるコメント機能を先に説明する（※というのも、コメント機能を使うと、コード内容の説明などがコード中に書けるようになるので、コードの解説がしやすくなるからだ。つまり解説側の都合であるが、ご了承いただきたい）。
今回、本稿で説明するのは、図1-d【再掲】における赤枠内のコードのみとなる。
本稿で示すサンプルコードの実行環境については、Lesson 1を一読してほしい。
Lesson 1でも示したように、本連載のすべてのサンプルコードは、下記のリンク先で実行もしくは参照できる。
Python言語の基礎文法
さっそく、コメント機能から説明していこう。
コメント
コメントとは、一般的には「何らかの対象に対する説明、論評、見解」という意味だが、プログラミングでは「コードに対する補足説明」としてよく使われる。コメントは、コードとしては無視され、実行されない部分となる。
Pythonでは、各行において#（ハッシュ文字）から後ろの部分は、コメントとして扱われて実行されない。例えば図1-D【再掲】では、リスト4-1のようにコメントが記載されている。このコメントは、その下に続く行のコードが「何をしているか」を説明する内容となっている。
# Display training progress by printing a single dot for each completed epoch（各エポックの完了のたびに「.」を描画することでトレーニングの進捗を表示する）
## ……コメントに続くコードは省略……
# Store training stats（トレーニング統計を保存する）
## ……コメントに続くコードは省略……
ちなみに、既存のコードの前に#を追記することで、コードをコメント化することをコメントアウトと呼ぶ。Google ColabやJupyter Notebookでコメントアウトを簡単に行うには、［⌘/Ctrl］＋［/］キーを押すだけだ（※［⌘/Ctrl］については、macOSでは［⌘］もしくは［Control］キーを押し、WindowsやLinuxでは［Ctrl］キーを押すという意味）。実際に押すと、入力カーソルがある行が、自動的にコメントアウトされる。すでにコメントアウトされている行であれば、逆にコメントアウトが解除される。この操作方法は、他のコードエディターや統合開発環境でも使えるケースがよくあるので、覚えておくてとても便利だ。下記のリスト4-2で実際にキーを何回も押してみると、その便利さが実感できるはずだ。
import tensorflow as tf # tfという名前でtensorflowモジュールをインポート
先ほどのリスト4-1の場合は、行頭に#が記載されているが、リスト4-2のように行の途中で書いてもよい。その場合は、#の直前まではPythonのプログラムコードとして認識される（つまり、リスト4-2ならimport tensorflow as tfというimport文が実行される）。
リスト4-1・4-2いずれも、#の後に半角スペースを入れているが、これは必須ではなく、スペースは入れなくてよい。ただし、TensorFlowの公式チュートリアル（例：図1-D【再掲】）がそうであるように、見やすくするために半角スペースを入れるのが、一般的だ。
なお、半角スペースの有無のようなルールはコーディング規約もしくはスタイルガイドと呼ばれ、会社や人によって異なる場合があるので、そのときそのときの状況に合わせたコーディング規約に従った方がいい。例えばTensorFlowにも「TensorFlow Style Guide」が用意されているので、これに従うのが望ましい。一般的には、Python公式の「PEP 8 スタイルガイド」（日本語訳）が有名で、これに従っておけばおおむね問題にはならないだろう。Python文法に慣れてきたら、ぜひこれらのスタイルガイドにも目を通すことをお勧めする。脱線したが、コメント機能に話を戻そう。
コメントは基本的に、リスト4-1・4-2のように1行1行記載していく必要がある。しかし場合によっては、複数行まとめてコメントにしたい場合もあるかもしれない。そのような場合は、'''〜'''（シングルクォーテーション、3つ）で挟むという応用テクニックが存在する（リスト4-3）。挟んだ複数行がコメント扱いになる。
'''
複数行の
コメントが
書けます
'''
'''は主に、ドキュメンテーション文字列（以下、docstring）と呼ばれる、（今後の連載の中で説明する）関数やクラスの説明を記載するための機能として使用されている。docstring以外の用途、つまり通常のコメント機能として'''を多用することはお勧めできない。通常のコメントを書きたい場合は、#で行ごとに書くことを筆者はお勧めする。
というのも、'''は実際にはコメント機能そのものではなく、次々回Lesson 5で説明する「文字列」機能を応用した使い方だからだ。実際に、リスト4-3をGoogle Colabで実行すると、「'\n複数行の\nコメントが\n書けます\n'」という文字列が出力されてしまうのを確認できる。
ちなみに、docstringを記載すると、PyCharmやJupyter Notebook、Google Colabのような作業環境で開発する際に、その関数やクラスのヘルプドキュメント（＝docstringヘルプ）が表示できるようになる（図6）。Google Colaboratory入門の「オートコンプリートとヘルプドキュメントの表示」で説明したように、このようなdocstringヘルプを表示するには、［Tab］キーを押せばよい。
図6 docstringヘルプの表示の例 docstringの書き方については、実践を積んでいくうちに必要になってから覚えればよいので、本連載では取り上げない。
APIリファレンス
さて、ヘルプドキュメントの話が出たところで、お勧めのヘルプ活用法について掘り下げておきたい。
前回のLesson 2の「モジュールの利用と定義」に、tf.keras.datasets.mnistというコードがあったのを覚えているだろうか。このコードの具体的な内容を知らずに一見しただけでは、例えば最後のmnistが「確実にモジュールである」とは、誰にも明言できないだろう。というのも、今後解説するクラスやそのメンバーであったり、関数であったりする可能性もあるためだ。
ではなぜ筆者は、このmnistがモジュールだと分かったのか？ 難しいことはない。それはAPIリファレンスを参照したからである。
API（Application Programming Interface）とは、コンピューター概論編［Lesson 3］で説明したように、ライブラリなどが持つ各種機能を、（主にアプリケーションの）プログラミング用に提供するためのインターフェース（＝接続点）のことだ。つまりAPIリファレンスとは、ライブラリ「TensorFlow」が提供するモジュールなど各種機能が説明されているリファレンス（＝参照ページ）のことである。APIリファレンスの別名として、APIドキュメントやヘルプなどと呼ばれることもある。
実際に次のリンク先を開くと、「tf.keras.datasets.mnist」というリンクがある。
*3 プログラミング言語における「シンボル（symbols、日本語訳で「象徴記号」）とは、プログラミング言語の構文・機能で定義された個別の要素（モジュールや､今後説明するクラスや関数など）のことである。具体的にはtensorflow／keras／datasets／mnistモジュールそれぞれがシンボルである。
「tf.keras.datasets.mnist」のリンクをクリックして開くと、図7のように表示され、「Module: tf.keras.datasets.mnist」と記載されてあり、これがモジュール（Module）だと分かった。
さらに、図7の上方にある「Defined in tensorflow/keras/datasets/mnist/__init__.py」（※2018年10月時点の情報。ライブラリ機能は絶えず更新されており、本稿を読む時点では記載内容が変わってしまっていることに注意してほしい）という記載されたリンク部分をクリックすると、mnistモジュールのソースコードが記載されたページが開く（はずなのだが、URLが間違えているようでリンク切れとなっていた。ライブラリの内容が頻繁に更新されるため、APIリファレンスのリンク切れはよくある）。
TensorFlowはオープンソースのライブラリであるので、GitHubというソース管理サイトで「tensorflow/tensorflow」という名前（＜GitHubのアカウント名＝「tensorflow」＞/＜リポジトリ名＝この場合はコード管理対象となるライブラリ名「TensorFlow」＞）でオープンに公開されており、誰でもアクセスできる（※参考までに、TensorFlowバージョン1.12であれば、図7にあるload_data関数の実装内容は「tensorflow/tensorflow/python/keras/datasets/mnist.py」というリンク先で参照できる）。ディープラーニングの実践レベルが上がっていくと、ライブラリ「TensorFlow」の中身がどのような挙動になっているかを調べたくなる場面が出てくるかもしれない。そのような場合には、TensorFlowのソースコードを簡単に調べられるようになっているわけである。オープンソースであることは、無料であること以上に、こういった点でも利用者にとって有益だ。
まとめると、「記載されている単語がモジュールかどうか分からない」「コードの機能内容が分からない」という場合は、筆者がやったように、まずAPIリファレンスを検索するのがお勧めだ。今回見たAPIリファレンスは英語であるが、日本語の参考訳がある場合もあるし、翻訳サイトで変換するなどすれば何とか使いこなせるので、ぜひ積極的に活用してほしい。
つづく
今回は「コメント」と「APIリファレンス」について説明した。次回は、Python言語の基礎中の基礎とも言える「変数」の基本「bool型（ブール型）」「int型／float型（数値型）」「str型（文字列型）」について紹介する。
Copyright© Digital Advantage Corp. All Rights Reserved.
注目のテーマ
ITmediaはアイティメディア株式会社の登録商標です。