On Fri, May 29, 2009 at 5:36 PM, Simon Laws <[email protected]> wrote: > I've noticed over the last couple of months that we have, on some > occasions, become a little lax about adding the "why" alongside the > "what" in our commit comments. Particularly problematic when there is > no JIRA to refer to. I'm as much a culprit as anyone else so I'm not > throwing rocks here but it would be useful to me if, as we're > reviewing each others changes, we can call out when we think the > comment isn't sufficient or clear enough so that the justification can > be updated and it becomes a matter of record. I seems that there are > some innovative discussions firing up on 2.x and it would be good to > be able to help people follow the twists and turns as best we can. > > Is this a fair observation? > > Simon >
+1. Commit comments saying why not what with as much detail as is necessary to help others understand the change remembering that there's lots of room so more than one sentence is ok if required. Also several small discrete commits are easier to understand than one commit which has several different changes. Also try to do formatting changes separately because it can be real hard to see whats changed if formatting is mixed with other code changes. And another type i find a bit irksome is comments that only mention a JIRA number eg "Fix TUSCANY-xxxx" but not what the JIRA is about so you have to go look it up yourself. ...ant
