コメントの文脈

正しいコメント文とは何かを考えていた。 正直に言うと、コメント文をコードから追い出して別レイヤーに配置する方法を考えていた。 それにはまず正しいコメント文のあり方を把握しなければならない。 コメント文は色々と文句を言われるが、結局実行に影響を与えないので、捨て置かれているのだと思う。 文句はたとえば、多すぎる、少なすぎる、コードの実態と合わなくなる、何に対するコメントか不明確、などだ。

最後の文句の解消を考えよう。 まともなコメントであれば、それは何らかの対象に関するもののはずだ。 たとえば変数の値に対する、特定の値しか使わないとか、単位は何だとか、といった注釈。 たとえば関数の引数や型に関する説明、処理内容や、アルゴリズムの選択について。 たとえばコードブロックの役割や、不変量の説明。 したがって、コメントはその説明される対象と同じスコープを持つと思って良い。 スコープを持つものだとすれば、オブジェクトであればよいだろう。 ただ、コメントされる対象と一緒に初期化されるだけのオブジェクトでは、 コードブロック特にコメントされる対象が単に意味的なまとまりとしか言えない数行のコードブロックの場合に、不明確である。 従って、逆にコメントがスコープを作り出すほどの力を持っていた方が適切とも言える。

ここから話は Python に限定される細道に入る。 他の言語では変数スコープの規則が違って、やりにくいかもしれない。 という注意を先にしておこう。 Python ではコンテキストマネージャーという仕組を使うことで、with 文により好き勝手にスコープを切れる。 このとき、変数のスコープはあくまで関数単位(関数の外にあるものはモジュール単位)になるので、このスコープはあくまでコンテキストマネージャーによって提供されるコンテキストの話である。 コメントをコンテキストマネージャーにすることで、コメントの影響範囲は明確化できる。 たとえば、

# A をする
a = A()
# B をする
if a に関する条件:
    B(a, 追加の引数)
else:
    B(a, 違う引数)

のようなコードが、

with Comment("A をする"):
    a = A()
with Comment("B をする"):
    if a に関する条件:
        B(a, 追加の引数)
    else:
        B(a, 違う引数)

のように書けたら良いのではないだろうか。

ということで Python のパッケージを作った。

comment-object

まあ、実際に使ったらインデントが深すぎて死にそうだけど。