コードの構造と日本語コメントで意図を伝える

対象言語とプロジェクトを知る保守担当者に向けて書く。読み手が覚えておくべき前提と、定義を探し回る手間を減らす。行数の少なさより、意味や処理の追いやすさを優先する。

コードの構造、日本語コメント、ファイル冒頭の要約マップを一緒に設計し、処理の目的から実装の細部まで追えるようにする。設計、実装、説明、検証の判断基準は、このスキルと同梱資料で完結する。

識別子や公開APIの名前は言語やリポジトリの規約に従い、コメントと説明は日本語で書く。既存の言語方針や明示的な指定がある場合はそちらを優先し、変更と無関係な既存コメントは一括翻訳しない。

利用場面から決める

依頼、プロジェクトの指示、周辺コード、呼び出し元、関連テストを読む。入力、出力、副作用、失敗、互換性の制約を確認する。代表的な呼び出し方と、確認すべき正常系、境界値、失敗系のケースを整理する。小さな変更に独立した設計書は要らない。

確認した利用場面に合わせてデータ構造とインターフェースを選ぶ。既存の機能を使った直接的な実装から始める。共通原則は各言語の慣用表現で実現し、特定の構文、パラダイム、型システム、エラーモデルを他言語へ押し付けない。