連載
» 2019年02月07日 05時00分 公開

機械学習&ディープラーニング入門(Python編):Lesson 3 コメント ― Python基礎文法入門、APIリファレンスの使い方

Python言語の文法を、コードを書く流れに沿って説明していく連載。今回は、コードの中で頻繁に使われるコメント機能を説明。さらに、コーディング作業で常用するAPIリファレンスの使い方について紹介する。

[一色政彦,デジタルアドバンテージ]

この記事は会員限定です。会員登録(無料)すると全てご覧いただけます。

「機械学習&ディープラーニング入門(Python編)」のインデックス

連載目次

ご注意:本記事は、@IT/Deep Insider編集部(デジタルアドバンテージ社)が「deepinsider.jp」というサイトから、内容を改変することなく、そのまま「@IT」へと転載したものです。このため用字用語の統一ルールなどは@ITのそれとは一致しません。あらかじめご了承ください。

 前回は「モジュール」について説明した。今回は、参考説明などをコード内に記述するための「コメント」機能について説明し、さらにPythonのコードを記述する際に参考になるヘルプドキュメント「APIリファレンス」を紹介する。脚注や図、コードリストの番号は前回からの続き番号としている。

 なお本連載は、実際にライブラリ「TensorFlow」でディープラーニングのコードを書く流れに沿って、基礎文法が学んでいけるように目次を構成している。よって本来であれば、Lesson 1で掲載した図1-aのサンプルコードの3行目以降の説明に入るはずだが、今回はその原則から外れて、Lesson 1で掲載した図1-d(下に再掲)にあるコメント機能を先に説明する(というのも、コメント機能を使うと、コード内容の説明などがコード中に書けるようになるので、コードの解説がしやすくなるからだ。つまり解説側の都合であるが、ご了承いただきたい)。

図1-d【再掲】 TensorFlowの公式チュートリアルのサンプルコード(4) 図1-d【再掲】 TensorFlowの公式チュートリアルのサンプルコード(4)

 今回、本稿で説明するのは、図1-d【再掲】における赤枠内のコードのみとなる。

 本稿で示すサンプルコードの実行環境については、Lesson 1を一読してほしい。

 Lesson 1でも示したように、本連載のすべてのサンプルコードは、下記のリンク先で実行もしくは参照できる。


Google Colabで実行する
GitHubでソースコードを見る

Python言語の基礎文法

 さっそく、コメント機能から説明していこう。

コメント

 コメントとは、一般的には「何らかの対象に対する説明、論評、見解」という意味だが、プログラミングでは「コードに対する補足説明」としてよく使われる。コメントは、コードとしては無視され、実行されない部分となる。

 Pythonでは、各行において#(ハッシュ文字)から後ろの部分は、コメントとして扱われて実行されない。例えば図1-D【再掲】では、リスト4-1のようにコメントが記載されている。このコメントは、その下に続く行のコードが「何をしているか」を説明する内容となっている。

# Display training progress by printing a single dot for each completed epoch(各エポックの完了のたびに「.」を描画することでトレーニングの進捗を表示する)
## ……コメントに続くコードは省略……

# Store training stats(トレーニング統計を保存する)
## ……コメントに続くコードは省略……

リスト4-1 コメントのコード例(行全体)

 ちなみに、既存のコードの前に#を追記することで、コードをコメント化することをコメントアウトと呼ぶ。Google ColabやJupyter Notebookでコメントアウトを簡単に行うには、[⌘/Ctrl]+[/]キーを押すだけだ([⌘/Ctrl]については、macOSでは[⌘]もしくは[Control]キーを押し、WindowsやLinuxでは[Ctrl]キーを押すという意味)。実際に押すと、入力カーソルがある行が、自動的にコメントアウトされる。すでにコメントアウトされている行であれば、逆にコメントアウトが解除される。この操作方法は、他のコードエディターや統合開発環境でも使えるケースがよくあるので、覚えておくてとても便利だ。下記のリスト4-2で実際にキーを何回も押してみると、その便利さが実感できるはずだ。

import tensorflow as tf  # tfという名前でtensorflowモジュールをインポート

リスト4-2 コメントのコード例(行途中)

 先ほどのリスト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)。挟んだ複数行がコメント扱いになる。

'''
複数行の
コメントが
書けます
'''

リスト4-3 コメントのコード例(複数行)

 '''は主に、ドキュメンテーション文字列(以下、docstring)と呼ばれる、(今後の連載の中で説明する)関数やクラスの説明を記載するための機能として使用されている。docstring以外の用途、つまり通常のコメント機能として'''を多用することはお勧めできない。通常のコメントを書きたい場合は、#で行ごとに書くことを筆者はお勧めする。

 というのも、'''は実際にはコメント機能そのものではなく、次々回Lesson 5で説明する「文字列」機能を応用した使い方だからだ。実際に、リスト4-3をGoogle Colabで実行すると、「'\n複数行の\nコメントが\n書けます\n'」という文字列が出力されてしまうのを確認できる。

 ちなみに、docstringを記載すると、PyCharmやJupyter Notebook、Google Colabのような作業環境で開発する際に、その関数やクラスのヘルプドキュメント(=docstringヘルプ)が表示できるようになる(図6)。作業環境準備編[Lesson 3]の「オートコンプリートとヘルプドキュメントの表示」で説明したように、このようなdocstringヘルプを表示するには、[Tab]キーを押せばよい。

docstringヘルプの表示の例 図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、日本語訳で「象徴記号」)とは、プログラミング言語の構文・機能で定義された個別の要素(モジュールや、今後説明するクラスや関数など)のことである。具体的にはtensorflowkerasdatasetsmnistモジュールそれぞれがシンボルである。


Copyright© Digital Advantage Corp. All Rights Reserved.

RSSについて

アイティメディアIDについて

メールマガジン登録

@ITのメールマガジンは、 もちろん、すべて無料です。ぜひメールマガジンをご購読ください。