Pythonコメントの書き方｜docstring・NumPy・Sphinx向け記法まで整理して解説

Python のコメントは大きく分けると、行コメント、docstring、そして スタイル付き docstring の 3 つの層で考えると整理しやすくなります。

まず、コードの横や上に短く意図を書くのが行コメントです。次に、関数やクラスの使い方をまとまった形で残すのが docstring です。そして、その docstring をどう整った形式で書くかという流儀として、NumPy スタイル、Google スタイル、reStructuredText スタイルがあります。

特に reStructuredText スタイルは、Sphinx でドキュメントを生成するときに相性がよい書き方としてよく使われます。つまり、「コメントを書くかどうか」ではなく、どの粒度で、誰に向けて、何を残すのかで書き方を選ぶことが大切です。

Python を書き始めたばかりのころは、「とりあえず動けばよい」と考えがちです。すると、後から読み返したときに「この関数は何を返すのか」「この計算はなぜ必要だったのか」が見えなくなります。

逆に、全部に説明を書こうとして、コードを日本語でなぞるだけのコメントが大量に付くこともあります。コメントは多ければよいわけではなく、コードだけでは伝わりにくい意図を補うことに意味があります。

1. 行コメント

もっとも基本的なのが、# を使って書く行コメントです。これは、処理の意図や注意点を短く残したいときに向いています。

# 欠損値を除いて平均を計算する
valid_values = [x for x in values if x is not None]
mean_value = sum(valid_values) / len(valid_values)

この種のコメントは、コードを日本語でそのまま繰り返さないことが大切です。たとえば「sum する」「for を回す」と書くより、「なぜその処理が必要か」を書く方が役に立ちます。

2. docstring

関数、クラス、モジュールの先頭に三重引用符で書く説明文が docstring です。これは「この関数は何をするのか」「どう使うのか」をまとまって残すためのものです。

def celsius_to_kelvin(temp_c):
    """摂氏温度をケルビンへ変換する。"""
    return temp_c + 273.15

docstring は、関数の上に付ける見出しのような役割を持ちます。エディタ補完やドキュメント生成でも使われるので、単なるメモよりも少し公式な説明に近い位置づけです。

3. スタイル付き docstring

docstring は自由に書くこともできますが、実務では項目の順番を揃えた「スタイル付き docstring」がよく使われます。代表的なのが、NumPy スタイル、Google スタイル、そして reStructuredText スタイルです。

NumPy スタイルは、科学技術計算やデータ分析まわりのコードでよく見かけます。引数や戻り値を見出し付きでそろえるので、情報の並びが分かりやすいです。

def calc_area(radius):
    """
    円の面積を計算する。

    Parameters
    ----------
    radius : float
        円の半径。

    Returns
    -------
    float
        円の面積。
    """
    return 3.14159 * radius ** 2

Google スタイルは、項目名が簡潔で読みやすく、一般的なアプリケーション開発でも扱いやすい書き方です。

def calc_area(radius):
    """
    円の面積を計算する。

    Args:
        radius (float): 円の半径。

    Returns:
        float: 円の面積。
    """
    return 3.14159 * radius ** 2

reStructuredText スタイルは、Sphinx でドキュメントを生成したいときに特に使いやすい書き方です。Sphinx は Python プロジェクトのドキュメント生成でよく使われる仕組みで、reStructuredText スタイルの docstring と相性がよいです。

def calc_area(radius):
    """
    円の面積を計算する。

    :param radius: 円の半径
    :type radius: float
    :return: 円の面積
    :rtype: float
    """
    return 3.14159 * radius ** 2

Sphinx を使うプロジェクトでは、このような書式をそろえておくことで、関数説明をドキュメントとしてまとめやすくなります。つまり、コードの中の説明を、そのまま外向きの資料へつなげやすいわけです。

1 人で短いスクリプトを書くときは、行コメントと簡単な docstring だけでも十分なことがあります。ですが、複数人で触るコードや長く使うコードでは、docstring の書式を揃えた方が読みやすくなります。

特に、分析コード、ライブラリ、ユーティリティ関数集のように、あとで再利用されるものは、関数の説明がそろっているだけでかなり扱いやすくなります。さらに、Sphinx でドキュメントを出す前提があるなら、reStructuredText スタイルを選ぶ理由もはっきりします。

おすすめの考え方

短く補足したいなら行コメント、関数やクラスの説明なら docstring、複数の人が長く使うなら NumPy や Google などの書式で統一、Sphinx で文書化するなら reStructuredText スタイルも有力、という順で考えると判断しやすいです。

ありがちな失敗は、コードをそのまま日本語で言い換えただけのコメントを大量に付けることです。たとえば「変数 x に 1 を足す」と書いてあっても、x += 1 を見れば分かります。

また、docstring の形式が関数ごとにばらばらだと、かえって読み手が迷います。プロジェクト単位で 1 つの流儀を決めておく方が、全体の見通しはよくなります。

さらに、コメントが古くなるとコードより危険です。コードを直したのに説明を直し忘れると、読み手は誤解しやすくなります。コメントは書いたら終わりではなく、コードと一緒に保守する必要があります。

Sphinx を前提にしているのに、docstring の形式が途中から崩れると、生成されるドキュメントの読みやすさも落ちやすくなります。文書化まで見据えるなら、書式の揺れは早めに抑えた方が扱いやすいです。

Python のコメントは、短い補足、関数の説明、書式の統一という 3 つの層で見ると整理しやすくなります。どれか 1 つが万能なのではなく、場面に応じて役割が違います。

まずは、行コメントで意図を書くこと、関数に短い docstring を付けることから始めるだけでも十分です。そのうえで、コードが増えてきたら NumPy スタイルや Google スタイルのような統一書式へ進むと、保守しやすい形に育てていけます。さらに、Sphinx でドキュメント化したいなら、reStructuredText スタイルを視野に入れると、コードと資料をつなぎやすくなります。