ChangeSetComments の翻訳です。
良いチェンジセットコメントの書き方
多くの ["Mercurial"] 関連ソフトウェアは[:ChangeSet:チェンジセット]コメントの最初の行を[:ChangeSet:チェンジセット]の内容を簡潔に記述したもとして取り扱います。
ですから最初の行は電子メールの題名を書くつもりで書いてください。
- 単独で意味がわかる
- 短い(65文字以下が目安)
- チェンジセットの内容を
などが重要です。
良いコメントの例:
First stab at the veeblefrotzer subsystem Implemented using the McWhirly/O'Blivet technique. Displays correctly on the twelfth of every month, but doesn't yet work during the other 27-30 days.
以下の点で優れています。
- 一行目で変更内容が簡潔に記述されている
- コメント全体も短かくわかりやすい
- 既知の問題点が書かれている
悪いコメントの例:
Implemented the veeblefrotzer subsystem, which uses the McWhirly/O'Blivet scheme for envolvolution of the subducted whingnangle. See McWhirly, O'Blivet, "Acta Exsanguinata", vol. III, chap. 19 for a concise description of the technique, unless you can't find the chapter because someone has razored it out and papered it to the walls of their cube.
以下の点が問題でしょう。
- 一行目が独立していない
- パラグラフにわかれていないので読みにくい
- どうでもよい詳細が書かれている