|
Size: 1586
Comment:
|
Size: 1752
Comment: sync with ChangeSetComments@11 (update i18n links)
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| ChangeSetComments の翻訳です。 == 良いチェンジセットコメントの書き方 == |
#language ja |
| Line 4: | Line 3: |
| 多くの ["Mercurial"] 関連ソフトウェアは[:ChangeSet:チェンジセット]コメントの最初の行を[:ChangeSet:チェンジセット]の内容を簡潔に記述したもとして取り扱います。 | == 優れたチェンジセットコメントの書き方 == |
| Line 6: | Line 5: |
| ですから最初の行は電子メールの題名を書くつもりで書いてください。 * 単独で意味がわかる * 短い(65文字以下が目安) * チェンジセットの内容を などが重要です。 |
たいていの Mercurial 関連ツールは、 [[ChangeSet|チェンジセット]] コメントの1行目をチェンジセットの短い説明として扱います。 |
| Line 12: | Line 7: |
| 良いコメントの例: | ですから、1行目は電子メールの題名を書くつもりで書いてください: * 1行で意味をなし、 * 半角65文字以内で、 * チェンジセットの概要を示している必要があります。 優れたチェンジセットコメントの例を以下に示します: |
| Line 14: | Line 16: |
| First stab at the veeblefrotzer subsystem | veeblefrotzer サブシステムでの最初のスタブ |
| Line 16: | Line 18: |
| Implemented using the McWhirly/O'Blivet technique. | McWhirly/O'Blivet 法を用いて実装。 |
| Line 18: | Line 20: |
| Displays correctly on the twelfth of every month, but doesn't yet work during the other 27-30 days. |
毎月12日には正しく表示されるが、 それ以外の27～30日はまだ動作しない。 |
| Line 21: | Line 23: |
| Line 22: | Line 25: |
| * 一行目で変更内容が簡潔に記述されている * コメント全体も短かくわかりやすい * 既知の問題点が書かれている |
|
| Line 26: | Line 26: |
| * 1行目で変更内容が簡潔に記述されている * コメント全体に過不足がない * 既知の不具合について言及している |
|
| Line 27: | Line 30: |
| 悪いコメントの例: | これはダメな例です: |
| Line 29: | Line 33: |
| 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 36: | Line 40: |
| 以下の点が問題でしょう。 * 一行目が独立していない * パラグラフにわかれていないので読みにくい * どうでもよい詳細が書かれている |
どの辺が問題でしょう? * 1行目だけで意味が取れない * 段落が別れていない → 読みにくい * どうでもよいことが詳細に書かれている ---- CategoryJapanese [[ChangeSetComments|English]], [[ThaiChangeSetComments|ภาษาไทย]] |
優れたチェンジセットコメントの書き方
たいていの 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行目だけで意味が取れない
段落が別れていない → 読みにくい
- どうでもよいことが詳細に書かれている