This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.

Bug 26703 - In case an algorithm applies conditionally, the conditions should be defined in some kind precondition step
Summary: In case an algorithm applies conditionally, the conditions should be defined ...
Status: RESOLVED WORKSFORME
Alias: None
Product: WHATWG
Classification: Unclassified
Component: HTML (show other bugs)
Version: unspecified
Hardware: PC Linux
: P2 normal
Target Milestone: Unsorted
Assignee: Ian 'Hixie' Hickson
QA Contact: contributor
URL:
Whiteboard: blocked awaiting response from smaug ...
Keywords:
Depends on:
Blocks:
 
Reported: 2014-09-01 18:28 UTC by Olli Pettay
Modified: 2016-03-16 18:00 UTC (History)
3 users (show)

See Also:


Attachments

Description Olli Pettay 2014-09-01 18:28:23 UTC
As an example, when one follows 
http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#processing-model-4
it gives no clues that the algorithm might not apply to some input element types.

In order to know that, one needs to look at the specific type, for example
http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#hidden-state-%28type=hidden%29
and see that 'autocomplete' is listed as  'do not apply'.
Then one needs to find the definition for that 
http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#do-not-apply and from there to actually understand what
the whole thing means, 
http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#common-input-element-attributes

To get better readability, I suggest having a precondition step in each algorithm which applies conditionally.
So, before "1. If the element has no autocomplete attribute, then jump to the step labeled default."
there would be something like
Precondition: abort this algorithm immediately if the following preconditions don't hold:
              'autocomplete' attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#common-input-element-attributes">applies to</a> the element

Precondition should be used consistently, so that whenever it isn't there, reader would know that there are no preconditions.

I can see how the current spec is easier for the spec author, but it certainly is rather hard for follow for the reader.
And as with code, specs should favor readers.
Comment 1 Ian 'Hixie' Hickson 2014-09-18 17:31:50 UTC
The specific section cited here now starts with an explicit statement that it's only for <input type>s that apply.

Are there any other cases that are confusing?
Comment 2 Anne 2016-03-16 18:00:55 UTC
Olli, if you still find something confusing, please reopen or file an issue on GitHub. Thanks!