http://www.perlmonks.org?node_id=878306


in reply to Re: On comments
in thread On comments

Excellent thoughts.

Another, often-overlooked source of “documentation” is the change-history in the version control system, and any defect-reporting system records that you may have.   (And you do have them and you do use them, don't you?...   Ahh, yes.   Of course you do.   Of course.)

When you’re fixing a bug that was reported in the defect tracking system, record the defect-number in the comment.   When you check-in the change, update the defect record to show it.   This lets you perceive exactly what has changed in a module over time, and why.

This is a “dynamic” form of information, analogous to the “running log” that was routinely kept in the engine-room, or the “captain’s log” (“Stardate 4523.3 ...”) that was kept on the bridge.

Bonus Question:   what happened on that stardate?   Extra Vulcan-points if you don’t have to Google it...