|
Size: 1628
Comment: converted to 1.6 markup
|
← Revision 20 as of 2013-09-04 16:27:29 ⇥
Size: 1988
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 2: | Line 2: |
| <<TableOfContents>> | |
| Line 3: | Line 4: |
| ChangeSetComments の翻訳です。 == 良いチェンジセットコメントの書き方 == |
== 優れたチェンジセットコメントの書き方 == |
| Line 6: | Line 6: |
| 多くの [[Mercurial]] 関連ソフトウェアは[[ChangeSet|チェンジセット]]コメントの最初の行を[[ChangeSet|チェンジセット]]の内容を簡潔に記述したもとして取り扱います。 | たいていの Mercurial 関連ツールは、 [[ChangeSet|チェンジセット]] コメントの1行目をチェンジセットの短い説明として扱います。 |
| Line 8: | Line 8: |
| ですから最初の行は電子メールの題名を書くつもりで書いてください。 * 単独で意味がわかる * 短い(65文字以下が目安) * チェンジセットの内容を などが重要です。 |
ですから、1行目は電子メールの題名を書くつもりで書いてください: |
| Line 14: | Line 10: |
| 良いコメントの例: | * 1行で意味をなし、 * 半角65文字以内で、 * チェンジセットの概要を示している必要があります。 == 良い例 == 優れたチェンジセットコメントの例を以下に示します: |
| Line 16: | Line 18: |
| First stab at the veeblefrotzer subsystem | veeblefrotzer サブシステムでの最初のスタブ |
| Line 18: | Line 20: |
| Implemented using the McWhirly/O'Blivet technique. | McWhirly/O'Blivet 法を用いて実装。 |
| Line 20: | Line 22: |
| Displays correctly on the twelfth of every month, but doesn't yet work during the other 27-30 days. |
毎月12日には正しく表示されるが、 それ以外の27～30日はまだ動作しない。 |
| Line 23: | Line 25: |
| Line 24: | Line 27: |
| * 一行目で変更内容が簡潔に記述されている * コメント全体も短かくわかりやすい * 既知の問題点が書かれている |
|
| Line 28: | Line 28: |
| * 1行目で変更内容が簡潔に記述されている * コメント全体に過不足がない * 既知の不具合について言及している |
|
| Line 29: | Line 32: |
| 悪いコメントの例: | == 悪い例 == これはダメな例です: |
| Line 31: | Line 36: |
| 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. |
veeblefrotzer サブシステムを実装。沈降した whingnangle の envolvolution には McWhirly/O'Blivet の案を利用している。 手法の簡潔な説明については、 McWhirly, O'Blivet, "Acta Exsanguinata" 第3巻19章を参照のこと。誰かがそのページを 切り刻んでサイコロにしてしまって、その章が見当たらないということが 無い限りはね。 |
| Line 38: | Line 43: |
| 以下の点が問題でしょう。 * 一行目が独立していない * パラグラフにわかれていないので読みにくい * どうでもよい詳細が書かれている |
どの辺が問題でしょう? * 1行目だけで意味が取れない * 段落が別れていない → 読みにくい * どうでもよいことが詳細に書かれている == 関連項目 == * Mercurial へパッチを投稿する際は、コメントの書き方について [[ContributingChanges#Patch_descriptions|Patch descriptions]] を参照 |
| Line 44: | Line 54: |
[[ChangeSetComments|English]], [[ThaiChangeSetComments|ภาษาไทย]] |
Contents
優れたチェンジセットコメントの書き方
たいていの Mercurial 関連ツールは、 チェンジセット コメントの1行目をチェンジセットの短い説明として扱います。
ですから、1行目は電子メールの題名を書くつもりで書いてください:
- 1行で意味をなし、
- 半角65文字以内で、
- チェンジセットの概要を示している必要があります。
良い例
優れたチェンジセットコメントの例を以下に示します:
veeblefrotzer サブシステムでの最初のスタブ McWhirly/O'Blivet 法を用いて実装。 毎月12日には正しく表示されるが、 それ以外の27～30日はまだ動作しない。
以下の点で優れています。
- 1行目で変更内容が簡潔に記述されている
- コメント全体に過不足がない
- 既知の不具合について言及している
悪い例
これはダメな例です:
veeblefrotzer サブシステムを実装。沈降した whingnangle の envolvolution には McWhirly/O'Blivet の案を利用している。 手法の簡潔な説明については、 McWhirly, O'Blivet, "Acta Exsanguinata" 第3巻19章を参照のこと。誰かがそのページを 切り刻んでサイコロにしてしまって、その章が見当たらないということが 無い限りはね。
どの辺が問題でしょう?
- 1行目だけで意味が取れない
段落が別れていない → 読みにくい
- どうでもよいことが詳細に書かれている
関連項目
Mercurial へパッチを投稿する際は、コメントの書き方について Patch descriptions を参照