初めてのPython実践試験学習　第七回「PEP8を学ぶ～コメントの付け方～」

こんにちは、吉政創成　菱沼です。

今回もPythonエンジニア育成推進協会のPython 3 エンジニア認定実践試験の主教材「Python実践レシピ／技術評論社」を使って学びたいと思います。

前回から２章「コーディング規約」に入り、PEP8に書かれているコーディング規約をもとにコードのレイアウトに関するルールを学びました。今回は、コメントの付け方についてです。

Pythonのコーディング規約「PEP8」が必要な理由

Pythonのコーディング規約であるPEP8に定義されている内容は大きく3つに分類されるそうです。

  1. コードのレイアウトに関するルール
  2. コメントに関するルール
  3. 命名規約に関するルール

ちなみにPEP8の原文はこちらからお読みいただけます。
https://peps.python.org/pep-0008

前回は①を学習しましたので、今回は②のコメントに関するルールになります。（P22　2..1.3コメント）

コードの途中に「# 」の後にテキストが入っているのを見かけたことがあるかと思いますが、それがコメントです。複数名で開発する場合には、どういった時にコメントをつけるのかというのは事前に話し合われるようですが、今回は基本的なコメントのルールとして以下を学ぶことになります。

  • ブロックコメント
  • インラインコメント
  • docstring

ちなみに、もうコーディング規約については詳しいからOK！という方は、Pythonエンジニア育成推進協会が実施している無料の試験「PythonZen & PEP 8 検定試験」にぜひチャレンジしてみてくださいね。
https://pythonzen-pep8-exam.jp

ブロックコメント（P.22）

説明したいコードの前にコードと同じインデントで書くコメントのことをブロックコメントと言うそうです。ではここで教科書のサンプルコード（P.19）を載せてみます。

＜正しい書き方＞

# ブロックコメントcorrect_comment = “正しいコメント”

コードの前に［# ］（半角シャープと半角スペース）を入力した後に、テキストを書きます。

#の後に半角スペースがない場合や、スペースが2つ以上ある場合、また、#が2つ以上ある場合はコメントのコーディング規約上の書き方として間違いとなります。

インラインコメント（P.22）

コードと同じ行に書かれたコメントのことをインラインコメントと言い、書き方のルールには2つあるとのこと。ちなみに、PEP8的にはなるべくインラインコメントは控えるようにとされているそうです。

  • コードとコメントの間は、2つ以上のスペースを書く
  • コメント自体は、1つの#と1つのスペースの後ろに書く

例えばこんな感じで使われます。

＜正しい書き方＞

a = 1  # インラインコメント

ブロックコメントと同様、#の後に半角スペースがない場合や、スペースが2つ以上ある場合、また、#が2つ以上ある場合はコメントのコーディング規約上の書き方として間違いとなります。

docstring（P.23）

ドキュメンテーション文字列とも言われるこちらは、定義したモジュールや関数、クラス、メソッドについての説明を書く場合に利用されるもので、以下のようなルールで書かれるとのこと。

  • 関数やメソッドの説明はdefの直後に書く
  • “””で始まり、”””で終わる行とする
  • 説明が複数行の場合は、1行目の後に空行を書く

より詳細な内容はPEP257をお読みいただければと思いますが、上記以外の書き方のルールとしては以下も該当するようです。

  • docstring の前後に空行は無し
  • docstringの最初の行の文章は「.（半角ピリオド）」で終わらせる（”””文字.“”“）
  • 複数行に渡る場合、次行は最初の行と同じ個所にインデントする

原文を確認されたい方はこちらをどうぞ。原文にはモジュール、関数、メソッド、クラス、それぞれで書いておいた方が良い内容のヒントが書かれています。

●PEP 257 – Docstring Conventions
https://peps.python.org/pep-0257

ではここで、テキストに書かれていた書き方のサンプルです。

＜正しい書き方＞

def doc_string_sample():    “””関数の短い説明を書く.
    短い説明と内容の間には空行を1行あける    内容を書く    “”””
def doc_string_one_line():    “”””1行で終わるdocstringの書き方.”””

※トリプルダブルクォーテーションの前の空白は半角スペース4つです。
※テキストのサンプルコードにはピリオドが入っていませんでしたが、PEP257を読んで必要そうなので追記しています。

docstringの必要性

なぜdocstringが必要なのか、#によるコメントと何が違うのかを調べてみました。

  • IDEやエディタで説明文を表示できるようになるため、コードの理解が容易になる
  • 関数の引数や戻り値、例外の説明を書いておくことで、その関数が何をするものなのか、どう使えばいいものなのかを明確に伝えられるようになる

ということなのですが、どう明確に伝えるのかと言うと、例えば、［help (関数名)］と書いて実行すると、docstringの中に書いたテキストが表示されるようになるのだそう。

では、#で書いたものとの違いは何かと言えば、#のものはただのコメントで、構文上は無視されるものであり、プログラム的には書かれていない扱いだということで、helpを使用が何しようが何のアクションも起きないものになります。違いがはっきりですね。

参考：Python学習チャンネル by PyQ｜「コメント(#)とdocstring(“””)の違いは？」コメントとdocstringについて解説します

docstringの記述を助けてくれるツール

必要性は分かったものの…毎度書くのは大変そうだなぁと思っていたら、IDEやエディタによっては自動でdocstringを書いてくれるツールがあるそうです。VS codeではPython Docstring Generatorというものが用意されているようです。

なお、テキストで紹介されていたのは、Python製のドキュメント生成ツールのSphinxというもので、こちらはdocstringからドキュメントを作ってくれるものだという事でした。

Python製のドキュメント生成ツールSphinx　https://www.sphinx-doc.org/ja/master/
※上記のサイトには各スタイルの特徴がドキュメントで比較されています。
https://www.sphinx-doc.org/ja/master/usage/extensions/napoleon.html

ちなみにdocstringの中にある引数や戻り値などの書き方はPEP8、PEP257では定義されておらず、よく利用される定義は以下のURLに書かれているものだそうです。

reStructuredText
https://www.sphinx-doc.org/ja/master/usage/restructuredtext/domains.html#info-field-lists

Google Python Style Guide
https://google.github.io/styleguide/pyguide.html

numpydoc
https://numpydoc.readthedocs.io/en/latest/format.html

それではきりが良いので、今回はこちらで終了です。お付き合いいただきありがとうございました。

ぜひPEP試験も受験してみてくださいね。

https://pythonzen-pep8-exam.jp

実践試験について知りたい方は以下をご覧ください。

●Python3エンジニア認定実践試験

https://www.pythonic-exam.com/exam/jissen

PAGE TOP