Pythonコメントの書き方｜#・複数行・docstring

コメントは人間のために書くもの

Python はコメントを完全に無視します。仕組みとしてはそれだけの話です。コメントとして書いた部分はインタプリタからは見えず、あくまでコードを読む人のために存在しています。そして、そのコードを読むのはたいてい半年後の自分で、「昔の自分、何考えてたんだ？」と首をかしげることになります。

とはいえ、コードを見れば一目瞭然のことをそのままなぞるだけのコメントは、書く価値がありません。いいコメントというのは なぜそうしているか を説明するものです。制約、回避策、コードからは読み取れない判断の理由といったものですね。何をしているか はコード自身がすでに語ってくれています。

# で書く1行コメント

Python のコメントの書き方で一番基本なのは、# のあとにメモを続ける形です：

行末に短いコメントを添える書き方もあります。慣例として、# の前には半角スペースを2つ以上空けるのが一般的です。

Pythonは文字列の外にある#を見つけると、その行の残りをコメントとして扱います。この「文字列の外にある」というのがポイントで、クォートの中に入っている#はただの文字として扱われます。

文字列の中にある #section-2 は URL の一部として扱われます。Python が「コメントモード」に切り替わるのは、文字列が閉じたあとの # だけです。

Python で複数行をコメントアウトする方法

Python には /* */ のようなブロックコメントはありません。複数行をまとめてコメントアウトしたいときは、各行の先頭に # を付けます。

あの # を手で一つずつ打っている人は、実はほとんどいません。まともなエディタには「行コメントのトグル」ショートカットがあって、選択した全行に # を付けたり外したりできます。

• VS Code: Cmd + / (macOS) または Ctrl + / (Windows/Linux)
• PyCharm: Cmd + / または Ctrl + /
• Vim: プラグイン次第ですが、vim-commentary なら 1 行は gcc、選択範囲は gc で切り替えられます。

自分のエディタのショートカットを一度覚えてしまえば、「このブロックをちょっとコメントアウトして動作を試す」が一瞬で終わります。

三重クォート文字列のテクニック(ただし本物のコメントではない)

たまに、次のようなコードを見かけることがあります。

厳密に言うと、これは「評価されて捨てられる文字列式」です。Python はパースして評価し、その結果を捨てているだけ。見た目はコメントっぽく 振る舞う けれど、本当のコメントではありません。スタイルとして許容されるのは、たった1箇所だけ。それが docstring です。

docstring：三重クォートを使っていい唯一の場所

docstring とは、関数・クラス・モジュールの先頭に置かれる三重クォートの文字列のことです。Python はこれをドキュメントとして認識し、実行時に help() 関数や __doc__ 属性から参照できるようにしてくれます。

docstring が便利な理由は大きく2つあります。

1. IDE、help()、ドキュメント生成ツールといった各種ツールが自動で読み取ってくれる点。関数の上に普通のコメントを書いてもこうはいきません。
2. 呼び出し側で関数の説明が表示される点。エディタで discount(...) にマウスを乗せると、docstring がツールチップとしてポップアップします。

docstring の書き方には PEP 257 という慣例があります。1行目に要約を1行で書き、空行を1行はさんで、必要なら詳細な説明を続ける、という形です。とはいえ、最初から形式にこだわりすぎる必要はありません。1行だけのシンプルな docstring でも、まったく書かないよりは遥かにマシです。

良いコメントとは何を書くものか

後々ハマらずに済む、いくつかのコツを紹介します。

• 「何をしているか」より「なぜそうしているか」を書く。 # ユーザーをループで回す は単なるノイズですが、# 503 のときはリトライ — デプロイ中に Redis がたまに落ちるため は金脈級の情報です。
• コードを変えたらコメントも直す。 間違ったコメントは、コメントが無いより有害です。古いコメントは後から読む人を積極的に誤解させます。
• コメントアウトしたコードを放置しない。 不要なら消しましょう。バージョン管理システムが覚えてくれています。コメントアウトされたコード片が散らばっているファイルは、あっという間に信用されなくなります。
• 当たり前のことは書かない。 x = x + 1 # x をインクリメント のようなコメントには何の価値もありません。

まとめ

コメントは書くのはタダですが、省いても大したコストにはなりません。読み手が「書いておいてくれてありがとう」と思うような情報 ― たとえば、なぜこの書き方で動くのかという微妙な理由、issue へのリンク、エッジケースに関する警告 ― を残したいときに使いましょう。関数やクラスを定義するときは docstring を書く。それ以外は、わかりやすい名前と小さな関数に語らせる。これが基本方針です。

ここまでで Python ファイルを読み書きするための基礎は一通り揃いました。次の章からは、いよいよ言語が実際に動き出します。変数、データ型、そして Python が扱える値について見ていきましょう。