| Indeed. VCS commit messages speak first to me in distinguishing the major "synch points" of a particular version's (branch's / shelf's / trunk's / tag's ) life cycle. Some of those synch points summarize an achieved goal (a concise "what" and "why"), but you have it spot on: VCS comments, at least as I write them, cannot match the finer granularity of inline comments. In writing VCS commit comments, I'm finding it most useful to compose these major-event commit events beginning with a <what> word written in all caps: o COPY out to SHELF <name> o MERGE in fixes for Ticket <id> from <what node> o RELEASE to TAG <id> as copy from <TRUNK | BRANCH <name>, MERGE back to TRUNK > o REVERSE MERGE my bad in Commit #<Rev>, detail in Ticket <id> Daily commits for work in progress don't get the all-caps treatment. My VCS (or perhaps my understanding of it) doesn't allow me line-level or block-level commit comments; those would reduce my inline comment density. That said, it's worth noting that the code base has been maintained through three VCSs, and independently annotated by two disjoint Ticketing systems, one of which went through an involuntary Ticket renumbering that was self-overlapping and irreversible. That taught me to prefix my Ticket references with a few "character constants" identifying the Ticketing system "du jour". A bare Ticket ID number has an implicit context; a "fixed prefixed" number communicates context whose value takes quantum jumps in value and user gratitude when the Ticketing system gets changed out. A cumulative top-of-the-file change log, in reverse chrono order. increases in value with age. Some of the judgement errors I made in years past become clear now, many times tripped across while looking for something else. Candor in commenting pays. |