The Palimpsest Effect

In-line comments are never up-to-date, which means that figuring out the state of a piece of code becomes an exercise in using the comments to re-construct a history of program changes, and from there figuring out the resulting changes in high-level behavior.

The American Heritage Dictionary defines palimpsest as

A written document, typically on vellum or parchment, that has been written upon several times, often with remnants of earlier, imperfectly erased writing still visible...

(The field of hermeneutics might offer some insight into how we interpret other peoples' designs and code.)

See also in french : EffetPalimpseste

---

Good ChangeLog entries in a VersionControl system help you work out why people thought a change was a good idea. The problem is that I've never seen good ChangeLog entries. They always describe what happened in this file/entity in a fairly low level of detail, rarely if ever related this to associated changes in other files, or explaining why the source was changed as well as why, or what other seemingly obvious changes were considered and discarded, along with why they were not used.

I'd be interested in what others think makes a GoodChangeLogEntry

---

CategoryCodingIssues