数日後に自分のコードを開いて「あれ？これ何のために書いたんだっけ？」と固まるのは、Blenderアドオン開発者の“あるある”です。
特に bmesh 操作や matrix（行列）計算が絡む部分は、たった数行でもすぐに“ブラックボックス化”します。本記事では、プロが実践する「未来の自分が100%理解できるコメント術」を体系的に解説します。この記事を読めば、保守性が劇的に向上し、バグの少ない美しいコードが書けるようになります。
0.まずはコメントの基本を理解しよう
Python（Blenderのスクリプト）でコメントを追加する方法は非常にシンプルです。
基本は「#（ハッシュ）」を入れるだけ
キーボードで Shift + 3（または「#」キー）を打つと、その右側の文字はすべて「コメント」になり、プログラムとしては無視されます。
# ここはコメントです。実行されません。
print("Hello Blender") # 行の途中から書くこともできます便利なテクニック「コメントアウト」
すでに書いたコードの頭に # をつけて、一時的に動かなくすることを「コメントアウト」と呼びます。
ショートカットキー
多くのエディター（VS Code等）では、行を選んで Ctrl + / (Macは Cmd + /) を押すだけで、一瞬でコメントのON/OFFが切り替えられます。
1. なぜBlenderアドオン開発にコメントが重要なのか？
BlenderのAPI（bpy）は非常に強力ですが、3D空間特有の複雑な概念を扱います。コメントは単なるメモではなく、「設計意図の記録」です。後でコードを確認したときに理解しやすいようにコメントを残すことで、バグの防止や仕様の把握がよりスムーズに対応可能となります。
- 【3D数学・幾何学的な計算】
なぜこの行列を掛けたのか、なぜこのベクトルを正規化したのか。 - 【コンテキスト（Context）の依存】
「なぜこのエディターで、このモードで実行する必要があるのか」という前提条件。 - 【APIの副作用】
特定のプロパティ操作が、他のUIやデータにどう影響するか。
2. Pythonコメント「3つの神器」＋ 1（型ヒント）
効率的な開発のために、これら4つの要素を使い分けましょう。
① 行コメント（#）：コードの「Why（なぜ）」を書く
コードを見ればわかることは書かず、「意図」を書くのが鉄則です。
# OK: ユーザー設定のオフセットを基準にミラー反転距離を決定
offset = context.scene.my_addon_props.offset注意点: コードを変更したのにコメントを古いまま放置するのは「嘘のコメント」となり、バグの温床になります。常にセットで更新しましょう。
② Docstring（ドキュメント文字列）：ユーザーへの「ツールチップ」
関数やクラスの直下に書く """文字列""" です。これはBlender上でボタンにマウスを置いた際の説明文（ツールチップ）としても利用されます。
def align_objects_to_grid(grid_size: float):
"""
選択オブジェクトをグリッドに整列。
Args:
grid_size (float): 整列の単位となるグリッド幅
"""
# 処理内容...③ TODOコメント：作業漏れを防ぐ「備忘録」
VS Codeなどのエディターでは TODO と書くと強調表示されるため、将来の課題を忘れずに済みます。
# TODO: Blender 5.0の新しいメッシュAPIへの移行を検討【重要】型ヒントで“実行前”にバグを防ぐ方法
型ヒントは、変数や関数の引数が「何であるか」を明示する仕組みです。単なる説明文ではなく、エディター（VS Codeなど）と連携して実行前にミスを防ぐ強力な安全装置になります。
def move_object(obj: bpy.types.Object, distance: float) -> None:
# 引数の型が明示され、開発中の入力補完が劇的に向上する
obj.location.x += distance型ヒントを導入する3つの劇的メリット
- 【最強の入力補完】
obj.と打った瞬間に、使えるプロパティが候補に出ます。 - 【凡ミスを即座に発見】
数値を入れるべき場所に文字を入れると、エディターが警告してくれます。 - 【コードが「仕様書」になる】
誰が見ても使い方が一目瞭然になります。
3. Blender特有！可読性を極める「注釈術」
「poll()」メソッドに理由を添える
「なぜ今、このボタンが押せないのか」を言語化しておくと、デバッグが10倍速くなります。
@classmethod
def poll(cls, context):
# 3Dビューポート上で、かつメッシュの編集モード中のみ実行を許可
return context.area.type == 'VIEW_3D' and context.mode == 'EDIT_MESH'行列（Matrix）演算の意図を言語化する
手順を分解して書くことで、数カ月後の自分を助けます。
# 1. ワールド座標系での現在の回転を取得
# 2. ローカル軸に基づいて45度回転させる行列を作成
# 3. 新しい行列を適用し、スケールを維持したまま回転を更新依存関係と「罠」を回避するコメント
つまずきやすい「データ構造の依存」についても注釈を残しましょう。
# 注意：bmesh.from_edit_mesh は編集モード専用。
# オブジェクトモードで利用した場合は bm.free() を手動で呼ぶ必要がある。4. 「美しいコード」の4大鉄則
| 鉄則 | 内容 |
|---|---|
| Why（なぜ）を書く | 「何をしているか」ではなく、その設計を選んだ「理由」を書く。 |
| 鮮度を保つ | コードを直したらコメントも直す。メンテナンスされないコメントは害悪。 |
| セルフドキュメント | 変数名を is_enabled のように命名し、コメントなしで伝わる工夫をする。 |
| マニュアルへの誘導 | 複雑な仕様は doc_url（bl_info内）にまとめ、コード内は簡潔に。 |
5. まとめ
コメントは「未来の自分」を助ける最強の武器。PythonのDocstring、意図を書く行コメント、TODO、型ヒントを使いこなせば、Blenderアドオン開発は劇的に読みやすくなり、保守性も向上します。「資産」となるコードを残して、一流の開発者への一歩を踏み出しましょう！
これであなたのアドオンコードも、可読性と美しさを手に入れることができます！