[EEGuy]

Expressing "The Five Ws"[1] (plus the "How") in and about code, adapts that excellent journalistic tradition [1].

I'm constantly trying to find a balance. Definitely the "Why" of a code change is most difficult to self-document.

A style I've used for decades, a bit wordy, but useful in merging change sets, keeps a change log at the top of every module / source file naming the person making a change (who), dating the change (when), tagging it with a pseudo-html tag [wrapping an area of code changes in the body of the source file] (what and where), and at the top, a reference to the failure case or test case (why) explaining why it was necessary to make this change.

When one change spans multiple files, I dedicate one source file to contain the detail, and all the others make reference comments to the one source file containing the detail.

[1] https://en.wikipedia.org/wiki/Five_Ws

[subb]

This is interesting because what you are basically doing is what your VCS should do. However, even if you write good commit message (why) and make localized commit (what, where, who, when), the visualization that you get from your technique is not matched by the VCS. Plus I guess it's more high-level than what the VCS gives you. You probably don't add something to your change log if all you did was fix a typo.

Also, a changelog only documents the why of modifications, not the why of existence of a class, function, etc.

[EEGuy]

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.

[ZoFreX]

Another way to achieve this goal is to include a ticket number in any commit relating to it. That way you can easily find out why the changes had to be made at that time (assuming your tickets have good descriptions - they do, right?)

[EEGuy]

Oh yes, very much so. As I use it, a Ticket can carry, as necessary:

o A discovery and progress narrative, useful to regain working context after long interruption, fit neither for inline comments nor VCS commit comments.

o A research and reference document list

o A related Ticket reference list

o A summary recovery plan and record

o A summary integration plan and record