前提
VCSのコミットメッセージ以外に、ソースにバージョンコメントを残すという場合。
v0.1のコメント例
既存のコードのバージョンアップ時は以下のようなコメントでいいと思う。
- v0.2 2015/11/23 xxという機能を追加した
しかしながら、新規作成の場合、一番最初(v0.1)のバージョンコメントは何が適切なのだろうか?
v0.1でいくつもの機能を実装してしまう場合での考察。
以下、例と考察。
- v0.1 2015/11/23 とりあえずの機能を実装した
- どこまでが「とりあえず」なのか分からない。
- v0.1 2015/11/23 funcAAA()、funcBBB()、procXXX()を実装した
- どの関数が最初に作られたか分かる。
- v0.1で何が実装されていたか分かるのがいいのだろうか?
- v0.2以降のコメントと対比すれば分かることかもしれないが、v0.2以降のコメントなどから読み解くのに時間がかかる場合、v0.1だけで分かる方がいいと思う
- v0.1 2015/11/23 新規作成
- 2015年11月23日から作っているという情報のみ分かる
gitのコミットメッセージでは"1st commit"がよく使われる。
それと対応するのは「新規作成」だろうか。
v0.1のコメントで知りたいこと
v0.1のコメントから知りたいことは何だろう?
- 作成日時
- 作業時間の振り返りに使う? 2015/07/11から始めた.
- そのファイルがどれくらい古いものかはわかる.
- 他のプロジェクトでも共用されるファイルである場合、同じバージョンかどうかを知りたい
- 元ファイル更新時に、他のプロジェクトへのバージョンアップ対応する時
- VCSの共有なりgit submoduleなりを使えば回避できることかもしれない
現状(2015/12/09)では、上記の例の項目2 (v0.1 2015/11/23 funcAAA()、funcBBB()、procXXX()を実装した)というコメントが最初のバージョンコメントとしていいように考えている。
その際、複数の記載をする場合は、以下のような記載がいいように思う。
v0.1 2015/11/23
- procXXX()を追加した
- funcBBB()を追加した
- funcAAA()を追加した