コメント（# と {# #}）

# Python: 一行コメント — # 以降、行末まですべてコメントになります。
# コードの上や行末に書きます。

"""
Python: docstring — 三重引用符で囲んだ文字列です。
関数・クラス・モジュールの先頭に書くとドキュメントとして扱われます。
Flask では @app.route() に付けた関数の docstring が
エンドポイントの説明として各種ツールから参照されます。
"""

次のコードも別の記述例です。

{# Jinja2 テンプレート: 一行コメント — HTML に出力されません。 #}

{#
  Jinja2 テンプレート: 複数行コメントは {# から #} の範囲で書けます。
  Django テンプレートの {# #} と同じシンタックスです。
#}

{# HTML コメントとの違い:  はブラウザに届きます #}

Flask のルート関数（ビュー関数）に docstring を書くと、次のような場面で参照されます。

Flask アプリケーションでのコメントと docstring の使い方を確認します。

app.py

# app.py — Flask アプリのエントリーポイントです。

from flask import Flask, render_template, abort

app = Flask(__name__)

# 商品データ（実際のアプリではデータベースから取得します）
PRODUCTS = [
    {"id": 1, "name": "item_a", "price": 1000},
    {"id": 2, "name": "item_b", "price": 2500},
    {"id": 3, "name": "item_c", "price": 800},
]

@app.route("/")
def index():
    """
    トップページを表示します。
    全商品の一覧を product_list.html に渡してレンダリングします。

    Returns:
        str: レンダリング済みの HTML 文字列。
    """
    # is_available フィルターを追加する場合はここで絞り込みます。
    return render_template("product_list.html", products=PRODUCTS)

@app.route("/product/<int:product_id>")
def product_detail(product_id):
    """
    商品詳細ページを表示します。

    Args:
        product_id (int): 表示する商品の ID。

    Returns:
        str: レンダリング済みの HTML 文字列。

    Raises:
        404: 指定した ID の商品が存在しない場合。
    """
    # next() で条件に一致する最初の要素を取得します。
    # 見つからなければ None を返し、404 を返します。
    product = next((p for p in PRODUCTS if p["id"] == product_id), None)
    if product is None:
        abort(404)
    return render_template("product_detail.html", product=product)

if __name__ == "__main__":
    app.run(debug=True)

Jinja2 テンプレートでのコメントの書き方を確認します。

templates/product_list.html

{# product_list.html — 商品一覧を表示するテンプレートです。 #}
{% extends "base.html" %}
{% block content %}

{# タイトルセクション #}
<h1>商品一覧</h1>

{#
  以下のリストはビュー関数から渡された products 変数を使います。
  ソートや絞り込みはビュー側で実施済みです。
#}

<ul>
  {% for product in products %}
    <li>{{ product.name }} — {{ product.price }} 円</li>
  {% else %}
    <li>商品がありません。</li>
  {% endfor %}
</ul>

{# HTML コメントはブラウザのソースに残ります（機密情報は書かない） #}
<!-- フッターエリア -->

{% endblock %}

HTML コメントに内部情報を書く

HTML コメント（『<!-- -->』）はブラウザのソースに残ります。デバッグ情報・内部 URL・設定値などを書くと、ページのソースを見るだけで読み取れてしまいます。Jinja2 テンプレートコメント（『{# #}』）を使えば HTML に出力されません。

{# NG: HTML コメントに機密情報を書くと外部から見える #}
<!-- API endpoint: /internal/admin/reset -->

{# OK: Jinja2 コメントなら HTML に出力されない #}
{# 管理用エンドポイントは admin blueprint を参照 #}

Jinja2 の変数構文をコメントに入れて展開される

Jinja2 テンプレートコメント（『{# #}』）の中に『{{ }}』や『{% %}』を書いても展開・実行されません。コメント内のこれらの構文はそのままコメントになります。ただし、コメントアウトしたつもりのコードが展開されると思い込んでいるケースがあります。

{# {{ user.name }} はコメント内では展開されない。変数は参照されません。 #}

{# {% if condition %} もコメント内では実行されません。 #}

Flask 開発では Python コードと Jinja2 テンプレートの2つの場所でコメントを書きます。Python ファイルでは『#』の一行コメントと三重引用符の docstring を使います。ルート関数の docstring は API ドキュメントツールやエディタのホバー表示から参照されます。

Jinja2 テンプレートでは『{# #}』がコメントです。Django テンプレートと同じシンタックスで、一行でも複数行でも使えます。レンダリング時に削除され、ブラウザに届く HTML には含まれません。HTML コメント（『<!-- -->』）はそのままブラウザのソースに残るため、内部情報やデバッグ用の記述にはテンプレートコメントを使うのが一般的です。