[Python-Dev] r87389 - in python/branches/py3k: Doc/library/unittest.rst Lib/unittest/case.py Misc/NEWS

[Raymond Hettinger]

On Dec 24, 2010, at 10:56 AM, Terry Reedy wrote:

> On 12/24/2010 11:09 AM, Michael Foord wrote:
>> On 22/12/2010 02:26, Terry Reedy wrote:
>>> On 12/21/2010 7:17 AM, Michael Foord wrote:
>>> 
>>> My first priority is that doc and code match.
>>> Close second is consistency (hence, ease of learning and use) between
>>> various AssertXs.
>>> 
>>>> Symmetrical diffs (element in first not in second, element in second not
>>>> in first) solves the problem without imposing an order on the arguments.
>>> 
>>> Where applicable, I prefer this as unambiguous output headings.
>>> 
>> Could you explain what you mean?
> 
> I was referring back to an output example symmetric diff that was clipped somewhere along the way:
> 
> In x not in y:
> ...
> In y not in x:
> ...
> 
> rather than just using -,+ prefixes which are not necessarily self-explanatory. 'Not applicable' would refer to output from difflib which necessarily is ordered.

FWIW, I think + and - prefixes are much better for diffs that some made-up verbiage.  People are used to seeing diffs with + and -.   Anything else will be so contrived that it's net effect will be to make the output confusing and hard to interpret.

If you want, add two lines of explanation before the diff:
    + means "in x, not in y"
    -  means "in y, not it x"

The notion  of "making symmetric" can easily get carried too far, which a corresponding loss of useability.  You get 95% of the benefit from two small changes:

* Change the parameter names from "actual" and "expected" to "first" and "second"
* Change the words "unexpected" and "missing" to "in first, not in second" and "in second, not in first".

We have a strong history in using +/- and shouldn't throw away its brevity and clarity.


Raymond