RE: [sarif] Editorial change: codeFlowLocation => threadFlowLocation

This change is now in the provisional draft. Again, let me know of any concerns.

Larry

From: sarif@lists.oasis-open.org <sarif@lists.oasis-open.org> On Behalf Of Larry Golding (Comcast)
Sent: Friday, June 1, 2018 9:25 AM
To: sarif@lists.oasis-open.org
Cc: Michael Fanning <Michael.Fanning@microsoft.com>
Subject: [sarif] Editorial change: codeFlowLocation => threadFlowLocation

I have filed Issue #187: Editorial: codeFlowLocation => threadFlowLocation. Michael and I consider this an editorial change because it is a pure rename, with no change in semantics. Here is the description of the issue:

We will rename the codeFlowLocation object to threadFlowLocation because it actually lives in a threadFlow, not in a codeFlow.

@michaelcfanning tripped over this yesterday, expecting the name to be threadFlowLocation. He argued that the current name violates the API principle of "least surprise".

Here is the historical background:

· The original name for this concept was annotatedCodeLocation. That was also a surprising name – nobody who walked up to a v1 codeFlow and wondered “What is the type of its locations?” would have guessed annotatedCodeLocation.

· In addition to being surprising, the name became just plain wrong when we moved annotations into the location object. Now every location could be annotated.

· The search for a new name came at the same time as we introduced the notion of an array of threads within a code flow. Michael and I struggled with whether to use codeFlow as the name for the outer object or the inner object. We settled on using it for the outer object because then we could invent threadFlow as the name for the inner object – whereas if we used codeFlow to name the inner object, neither of us could come up with a good name for the outer object.

· Having decided to use codeFlow for the outer object, the name codeFlowLocation really was an attempt to have it both ways – it was a name that would have been perfect if the inner object was named codeFlow – but it wasn’t.

Please let me know if you have any concerns about this.

Thanks,

Larry

sarif message