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］キーを押せばよい。
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モジュールそれぞれがシンボルである。
Copyright© Digital Advantage Corp. All Rights Reserved.