Re: Quote of the day

> If I've learned one thing as a systems engineer, it's that documenting
the *rationale* for requirements provides key context above and beyond even
"perfectly" formulated language in a specification.

This is a hobby horse of mine, for general purpose code: I think the school
of thought (which I associate with Rob Pike) that the code itself is the
best (or only viable) documentation is impossible and reckless.

The idea only works at the top level (where you name by intent) and the low
level (where you name by data structure, functionality, algorithm);  for
shallow code that is OK, but as soon as you get long and generified call or
type chains the "what and why" of names is lost in "how".   The code things
in between the top and bottom  can often be named by intent or operation
and you have to choose; and if you name by intent they become confusing to
be used in other situations, and if you name by operation you lose track of
the purpose or business requirement.  (IDEs help a lot, of course.)

For Schemas, there is a kinda-equivalent issue that if you make a schema
with reusable standard components, a user needs to know the context to
readily know what is going on: but we have no standard way to tell which
ancestor's name or value is relevant for the user.  For example, take the
(too shallow to be very convincing)

<dataset> <BillingAddress> <set> <po-box >22224<po-box> <suburb
code="2009">Pyrmont</suburb> <city >Sydney</city> <country
code="AU">Kangaland</country> </set> </BillingAddress> <OfficeAddress>
<set> <street >2/73 Union St</street> <suburb code="2009">Pyrmont</suburb>
<city >Sydney</city> <country code="AU">Australia</country> </set>
</OfficeAddress> </dataset>

A validator might say the horrid error message "Unexpected value for
country: Kangaland"  or if using assertions the better  "A country's name
should be on the approved list (at file countries.xml):
/dataset/BillingOffice/set/country has unexpected value 'Kangaland'."   But
the "dataset" and "set" are just noise: the info that the user  needs for
comprehension is just /*/BillingOffice//country

(As a related case, take Java NullPointerException.  It was only Java 14
that took the step of providing in the exception message information about
what code triggered the exception: but it doesn't tell what the field name
was when it was first created or assigned null way up the call chain, which
you need to know. (Of course, annotations can reduce the effect of the
problem, by static tests.))

So, in summary, there is a general unsolved problem for markup and
programming languages, of how to know which names up the ancestor or call
chain are generic/operational/functional and which relate to
intent/"semantics"/business-requirements.  And without that, it is not
possible to reliably avoid generating noisy, confusing or inadequate error
messages.

In Schematron, I guess you could do something like

<sch:diagnostic name="showSecondLevelContext">
  <sch:value-of select="concat('/*/', (ancestor::*)[2]/name(), '//',
./name()"/>
has unexpected value <sch:value-of select="."/>
</sch:diagnostic>

but a voice nags me that this should be information in the markup somehow:
for example an internal prolog declaration
<!ATTLIST BillingOffice isGoodSemanticContext CDATA "yes" #FIXED>
or
<?semanticElements BillingOffice PostalAddress ?>

I guess it may comes down to whether you think a schema is data to drive an
algorithm, or instead is data to participate in protocols allowing an
effective conversation between multiple humans and systems.

Cheers
Rick