TC review comments, hiding test cases (remove from formal spec)

["David A. Wheeler" <dwheeler@dwheeler.com>]

As you know, we (the formula subcommittee) have submitted our draft to the TC for commentary, and been awaiting their feedback.  Here are the comments I've received so far, and what I think we need to do.. but if you disagree, please speak up ASAP.

1. Test cases.

The main discussions have been on objections to including test cases in the spec, particularly as being normative.  We've been going back and forth on this issue, and frankly, I remain quite unconvinced.  One argument is that all we need to do is write perfect, unambiguous text without using test cases. That's a goal I laud and we should strive towards.. but since no previous spec has achieved that, doing the same thing as previous efforts but expecting a different result seems closer to the definition of insanity.  (I'm alluding to an old joke, "Insanity is when you do the same thing repeatedly but expect something different to happen.")  Another argument is that test cases can't cover all cases - true, but if their purpose is to clarify the text and ensure correct interpretation, that's a non-issue.  Antoher argument is that even including tests cases there may be ambiguity; which is true, but if they eliminate 80% of them, then that is still a good thing.  All agree that test cases are valuable and important, but yet somehow they're not important enough to be in a spec (!).

But our goal is to produce a spec, not an argument.  It appears very likely that including this information, even though it's very useful, will IMPEDE its becoming a standard. So even though I think this is NOT a good idea, I think we must NOT include the test cases in the official spec so the spec can be accepted. Instead, they should be in hidden text along with the other commentary. We might include 1-2 examples in each, which would help slightly.  This change will require some rewriting of text since what was unambiguous before might become ambiguous.

The test cases aren't being destroyed; they'll still be included in the annotated document, and of course they'll still be useful in determining what the specification SHOULD say.


2. Hiding Commentary

The first page clearly states that the notes, etc., will not be in the specification, but many reviewers just want to see what the FINAL spec will look like, and DON'T want to see all the rationale for why it is the way it is.  So we need to hide the other commentary, and turn on hiding by default.  Those who want to see the commentary can just turn it back on.

This was always the plan; I'd delayed it because we were going to switch formats, and that seemed like the best time to do it.  But sounds like we need to do it a little sooner.


3. Basis/YEARFRAC definition

We need to define the Basis/YEARFRAC stuff more exactly (esp. with the test cases removed).   This is a specific technical comment which I agree with.


I intend to walk through the document and hide all the commentary and test cases, and then repost.

Sound okay?  Let me know of any issues.  Thanks.

--- David A. Wheeler