W3C home > Mailing lists > Public > public-html@w3.org > January 2010

Re: spec verbosity and algorithms

From: Tab Atkins Jr. <jackalmage@gmail.com>
Date: Sat, 23 Jan 2010 08:58:34 -0600
Message-ID: <dd0fbad1001230658v290bd505m38ce6b68e7a3e50e@mail.gmail.com>
To: Julian Reschke <julian.reschke@gmx.de>
Cc: Karl Dubost <karl@la-grange.net>, "public-html@w3.org" <public-html@w3.org>
On Sat, Jan 23, 2010 at 1:47 AM, Julian Reschke <julian.reschke@gmx.de> wrote:
> Offlist I was asked why verbosity is a problem. The answer is really simple.
>
> As a reader, I want to know when two origins are equal. If this is defined
> in an 8-step algorithm, I'll have to work my way through this algorithm step
> by step and understand it.
>
> In particular, given the sheer amount of instructions, I *will* be confused
> because it really doesn't contain any surprises.
>
> This is a disservice to the reader.

It's a service to implementors, who have a trivial algorithm to follow
that is very difficult to get wrong and not really subject to
misinterpretation.

On the other hand, I see the value of *pairing* the verbose
explanation with a concise one that explains it in short, simple
language.  This algorithm could be paired with "If either A or B or
both are opaque identifiers, return true if they're equal and false
otherwise.  If neither are opaque identifiers, return true if their
host, scheme, port, and any additional data they may have if it
exists, are all equal; otherwise return false.

~TJ
Received on Saturday, 23 January 2010 14:59:27 UTC

This archive was generated by hypermail 2.3.1 : Monday, 29 September 2014 09:39:13 UTC