Python のコメントアウト基本と種類、PEP8・IDEショートカット完全ガイド

Contents

1 1️⃣ コメントの基本概念と種類
2 2️⃣ PEP8 が定めるコメントの書式
- 2.1 2.1 行長・空白規則
  - 2.1.1 コメント行長とコード行長の違い
- 2.2 2.2 docstring とコメントの役割分担
  - 2.2.1 Google スタイルの docstring 例
3 3️⃣ エディタ／IDE 別コメント操作ショートカット
4 4️⃣ 静的解析・整形ツールでコメント品質を自動チェック
- 4.1 4.1 実践的な CI 設定例（GitHub Actions）
5 5️⃣ 実務でのベストプラクティスと落とし穴
6 6️⃣ コメント品質チェックリスト
7 7️⃣ 次のアクション
8 まとめ

スポンサードリンク

1️⃣ コメントの基本概念と種類

種類	記法例	主な用途	ツール側の扱い
単行コメント	`# ここにコメント`	簡潔な補足、TODO 等	`flake8`・`pylint` が検出
複数行コメント（連続 #）	`# 行1<br># 行2`	一時的にコードを無効化したいとき	同上
ブロック文字列（triple‑quoted）	`''' コメント '''` または `""" コメント """`	docstring（モジュール・クラス・関数の説明）として利用。実行時には文字列オブジェクトになるので、コメント目的で使うのは非推奨	`flake8-comments` では警告（docstring とみなさない部分はコードとして扱われる）

ポイント
- コメントは「何を」より「なぜ」を説明する場です。
- # 系のコメントはインタプリタに無視され、静的解析ツールが確実に認識します。
- triple‑quoted の文字列リテラルは docstring 以外で使うと、実行時に不要なオブジェクトが生成されます。

2️⃣ PEP8 が定めるコメントの書式

2.1 行長・空白規則

項目	推奨スタイル	補足
行頭コメント	`#` の後に半角スペースを必ず入れる（例: `# TODO:`）	インデントレベルはコードと合わせる
インラインコメント	コードから最低 2 スペース空け、続けて `#` を書く	例: `x = func() # 戻り値をチェック`
コメント行の長さ	72 文字以内（PEP8 が推奨）	コード行は 79 文字（Python 3.11 以降は 88 文字がデファクトスタンダード）と区別する必要があります。長くなる場合は改行して続けます。

コメント行長とコード行長の違い

コメント行：ドキュメントとして読むことを前提に、可読性確保のため 72 文字以内に収めるのが慣例です。
コード行：実装上必要な情報量に応じて 79〜88 文字まで許容されます（black のデフォルトは 88 文字）。

この違いを意識すると、エディタや CI ツールが出す警告の意味がすぐに分かります。

2.2 docstring とコメントの役割分担

種別	記述対象	主な書式例
docstring	モジュール・クラス・関数／メソッドの「何をするか」「引数」「戻り値」など仕様情報	Google スタイル、NumPy スタイル、reST など
コメント	実装上の意図やアルゴリズムの背景、TODO / FIXME 等	`#` を用いた単行／インライン形式

実務での留意点
- docstring は Sphinx・pdoc·mkdocstrings などの自動ドキュメント生成ツールが唯一参照できる情報です。
- コメントはコードリーダー向けの補足であり、テストカバレッジや CI では除外されません。

Google スタイルの docstring 例

def fetch(url: str, timeout: int = 5) -&gt; bytes:
    &quot;&quot;&quot;指定した URL からデータを取得する.

    Args:
        url (str): ダウンロード対象の URL。
        timeout (int, optional): タイムアウト秒数。デフォルトは 5 秒。

    Returns:
        bytes: 取得したコンテンツ。

    Raises:
        ConnectionError: 接続に失敗した場合。
    &quot;&quot;&quot;
    # HTTP リクエストはネットワーク I/O がボトルネックになるため
    # タイムアウトを明示的に設定しておくことが重要です。
    response = requests.get(url, timeout=timeout)
    return response.content

def fetch(url: str, timeout: int = 5) -> bytes:

"""指定した URL からデータを取得する.

Args:

url (str): ダウンロード対象の URL。

timeout (int, optional): タイムアウト秒数。デフォルトは 5 秒。

Returns:

bytes: 取得したコンテンツ。

Raises:

ConnectionError: 接続に失敗した場合。

"""

# HTTP リクエストはネットワーク I/O がボトルネックになるため

# タイムアウトを明示的に設定しておくことが重要です。

response = requests.get(url, timeout=timeout)

return response.content

3️⃣ エディタ／IDE 別コメント操作ショートカット

エディタ	デフォルトショートカット	カスタマイズ例
VSCode	`Ctrl+/`（Windows/Linux） / `⌘+/`（macOS）	キーバインド設定で `"editor.action.commentLine"` を好きなキーに変更可能
PyCharm	同上 (`Ctrl+/` / `⌘+/`)	Settings → Keymap → Comment with Line Comment から再割り当て
Vim / Neovim	`gcc`（行単位）・`gc`（ビジュアル選択）※[tpope/vim-commentary] 推奨	プラグインなしでも `:s/^/# /`、解除は `:%s/^# //` で対応

Tips
- VSCode の拡張機能 Python はコメントトグル時にインデントに合わせて # を自動配置します。
- PyCharm は選択行すべてに # が付与され、再度同操作で除去できます。

4️⃣ 静的解析・整形ツールでコメント品質を自動チェック

ツール	コメント関連の主な機能	注意点
flake8	行長 (E501)、末尾空白 (W291) 等の基本チェック	標準ではインラインコメント前のスペース不足は検出しません
flake8‑comments（プラグイン）	`# TODO` の未完了タスクや、インラインコメント前に最低 2 スペースがない場合を警告	`pip install flake8-comments` が必要
pylint	`bad-whitespace`、`trailing-newlines`、`missing-docstring` 等の包括的チェック	設定ファイル (`.pylintrc`) で無視項目を調整可能
black	コメント行のインデント・折り返し（72 文字超過時は自動改行）	行長は 88 文字が上限なので、コメントだけは別途 `--line-length=72` を指定すると統一感が出ます
isort	主に import 順序の整形であり、コメント空白調整は行いません（誤解しやすい点）	コメント位置はそのまま保持されます

4.1 実践的な CI 設定例（GitHub Actions）

name: Lint &amp; Format

on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint-format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: &quot;3.12&quot;

      - name: Install tools
        run: |
          pip install flake8 flake8-comments pylint black isort

      - name: Run flake8 (including comments)
        run: flake8 .

      - name: Run pylint (docstring 必須チェック)
        run: pylint your_project/ --disable=all --enable=missing-docstring,bad-whitespace,trailing-newlines

      - name: Check black formatting
        run: black --check --line-length 88 .

      - name: Verify import order with isort
        run: isort --check-only .

name: Lint & Format

on:

push:

branches: [main]

pull_request:

jobs:

lint-format:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v3

- name: Set up Python

uses: actions/setup-python@v4

with:

python-version: "3.12"

- name: Install tools

run: |

pip install flake8 flake8-comments pylint black isort

- name: Run flake8 (including comments)

run: flake8 .

- name: Run pylint (docstring 必須チェック)

run: pylint your_project/ --disable=all --enable=missing-docstring,bad-whitespace,trailing-newlines

- name: Check black formatting

run: black --check --line-length 88 .

- name: Verify import order with isort

run: isort --check-only .

flake8-comments が有効になると、インラインコメント前のスペース不足や TODO: の未完了タスクが警告として表示されます。
black --line-length 88 はコード行長を緩めつつ、コメントだけは内部で自動的に 72 文字以内へ折り返します（設定変更可）。

5️⃣ 実務でのベストプラクティスと落とし穴

5.1 「簡潔さ」 vs 「冗長さ」

悪い例	問題点	改善ポイント
`# この関数は x を2倍にする`（docstring が空）	docstring が情報不足で自動ドキュメント生成に寄与しない	引数・戻り値まで記述した完全な docstring に置き換える
デバッグ用コードを `#` で残す	将来のリファクタリング時に混乱を招く	Git の履歴で管理し、不要なら削除する
インラインコメントが 120 文字以上	読みにくくなる	72 文字以内に収め、必要なら別行コメントへ分割

改善例（前後比較）

Before

def calc(x):
    &quot;&quot;&quot;計算&quot;&quot;&quot;  # docstring が極端に短い
    # TODO: エラーハンドリング追加
    return x * 2

def calc(x):

"""計算""" # docstring が極端に短い

# TODO: エラーハンドリング追加

return x * 2

After

def calc(x: int | float) -&gt; int | float:
    &quot;&quot;&quot;入力値を 2 倍して返す.

    Args:
        x (int or float): 計算対象の数値。

    Returns:
        int or float: 2 倍にした結果。
    &quot;&quot;&quot;
    # 将来的に負数や非数値へのエラーハンドリングを追加予定
    return x * 2

def calc(x: int | float) -> int | float:

"""入力値を 2 倍して返す.

Args:

x (int or float): 計算対象の数値。

Returns:

int or float: 2 倍にした結果。

"""

# 将来的に負数や非数値へのエラーハンドリングを追加予定

return x * 2

5.2 コメントとバージョン管理

原則：コードは Git の履歴で追跡し、不要になった実装は「コメントアウト」せずに削除する。
例外：一時的なデバッグや実験的変更はブランチを切って作業し、マージ前に必ずコメントを除去する。

5.3 CI での「コメント違反」検出フロー

flake8 → 基本的な行長・空白エラー
flake8‑comments → インラインスペース不足や未完了 TODO の警告
pylint → docstring が無い箇所を missing-docstring で検出
black → 自動整形済みかどうかのチェック（コメント折り返しも対象）

この順序により、コードレビュー の負荷が大幅に削減できます。

6️⃣ コメント品質チェックリスト

項目	確認方法
単行コメントの空白	`#` の直後に半角スペースがあるか（flake8‑comments が自動検出）
インラインコメントのスペース	コードから最低 2 スペース確保されているか
コメント行長	72 文字以内か（エディタで `ruler` 設定、または `black --line-length 88` の内部折り返し）
docstring の有無と形式	`pylint --enable=missing-docstring`、もしくは IDE の docstring テンプレート機能
TODO / FIXME の残存	flake8‑comments が警告を出すか確認
triple‑quoted をコメント目的で使用していないか	静的解析では検知しにくいため、コードレビュー時にチェック

7️⃣ 次のアクション

プロジェクトへ導入
requirements-dev.txt に flake8 flake8-comments pylint black isort を追加。
.pre-commit-config.yaml に以下を設定し、コミット前に自動チェックさせる。

repos:
  - repo: https://github.com/psf/black
    rev: 24.1b0
    hooks:
      - id: black
        args: [&quot;--line-length&quot;, &quot;88&quot;]
  - repo: https://github.com/PyCQA/flake8
    rev: 7.0.0
    hooks:
      - id: flake8
  - repo: https://github.com/adamchainz/flake8-comments
    rev: v1.0.2
    hooks:
      - id: flake8-comments
  - repo: https://github.com/PyCQA/pylint
    rev: v3.2.0
    hooks:
      - id: pylint
        args: [&quot;--disable=all&quot;, &quot;--enable=missing-docstring,bad-whitespace&quot;]

repos:

- repo: https://github.com/psf/black

rev: 24.1b0

hooks:

- id: black

args: ["--line-length", "88"]

- repo: https://github.com/PyCQA/flake8

rev: 7.0.0

hooks:

- id: flake8

- repo: https://github.com/adamchainz/flake8-comments

rev: v1.0.2

hooks:

- id: flake8-comments

- repo: https://github.com/PyCQA/pylint

rev: v3.2.0

hooks:

- id: pylint

args: ["--disable=all", "--enable=missing-docstring,bad-whitespace"]

チーム内で統一ルールを策定
コメント行長 72 文字、コード行長 88 文字（black デフォルト）に合わせる。
docstring は Google スタイルか NumPy スタイルのどちらかに統一し、テンプレートを IDE に設定。
定期的なレビュー
毎スプリントのコードレビューで「古いコメント」「TODO が残っていないか」チェックリストを使用。

まとめ

コメントは実装補足、docstring は仕様説明 と明確に役割分担する。
PEP8 の空白・行長ルール（コメント 72文字、コード 79〜88文字）を守り、flake8‑comments や pylint で自動検出できるようにする。
VSCode・PyCharm・Vim 等のショートカットは覚えておくと作業効率が大幅アップ。
静的解析＋フォーマッタ（black）＋CI の組み合わせで、コメント品質を継続的に保つ体制を構築できる。

このガイドラインをプロジェクトに取り入れれば、コードベースの可読性と保守性が飛躍的に向上します。ぜひ、今すぐチームの開発フローへ組み込みましょう。

スポンサードリンク