Subject: RE: [Isms] documentation style for SBSM: pseudo-code vs text

From: "McDonald, Ira" <[email-masked]>
Date: Tue, 7 Sep 2004 10:00:12 -0700

Hi,

I was actually leaning toward (c).  I find that long paragraphs
of text with sprinkled MUST/SHOULD/MAY are generally ignored or
misunderstood.

Pseudo-code with bullet headers preceded by something like the
following would be much less ambiguous:

"All assignments (expressed by '=') in the following pseudo-code
MUST be implemented by every conforming implementation."

Cheers,
- Ira

PS - I've found SHOULD to be useless in protocol specs.

Ira McDonald (Musician / Software Architect)
Blue Roof Music / High North Inc
PO Box 221  Grand Marais, MI  49839
phone: +1-906-494-2434
email: [email-masked]

-----Original Message-----
From: [email-masked] [mailto:[email-masked]]On
Behalf Of Wes Hardaker
Sent: Tuesday, September 07, 2004 11:48 AM
To: [email-masked]
Cc: [email-masked]; [email-masked]
Subject: Re: [Isms] documentation style for SBSM: pseudo-code vs text

>>>>> On Tue, 7 Sep 2004 11:37:00 -0400, "David B Harrington"
<[email-masked]> said:

David> I recommend text plus psuedo-code.

So both you and Robert are opting for (a) the original style then it
sounds like.  Paragraph style.

I don't want to do a full paragraph plus psuedo-code, however.  It's
redundant and more work than its worth.

-- 
Wes Hardaker
Sparta

_______________________________________________
Isms mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/isms

_______________________________________________
Isms mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/isms

---

From: Wes Hardaker <[email-masked]>
Date: Tue, 07 Sep 2004 10:05:57 -0700

>>>>> On Tue, 7 Sep 2004 12:35:21 -0400, "David B Harrington" <[email-masked]> said:

David> The pseudocode "session.status = CLOSED;" needs to be
David> supplemented with some text that indicates this assignment is
David> REQUIRED for interoperability.

To be clear: if pseudo-code was used, it would *always* be
supplemented with text describing what it meant if the intention
wasn't clear.  I don't think I picked a good example (I pulled a
paragraph at random) because I didn't include all the text that would
have an impact on the interpretation (like the entire section
describing the documentation conventions where the pseudo-code style
is described include the paragraph:

        Finally, it should be important to note that both these
	equations and the surrounding text must be read and understood
	in order to get the protocol correct.  IE, a successful
	implementation must take everything into account: both the
	text wording and the equations.  Order of execution of both
	the text and equations are critical for preserving some of the
	security properties of the SBSM protocol.

The real intent of my question was which would people prefer to read,
assuming all integral aspects of the protocol could be specified in
both ways.  If it was clear in both cases, which would people prefer?
It sounds like the general feeling is that it is not possible to
describe intents clearly in code much of the time, and thus text
should be preferred unless it is nearly impossible to mis-interpret
the code.

-- 
Wes Hardaker
Sparta

---

From: "Nelson, David" <[email-masked]>
Date: Wed, 8 Sep 2004 10:28:54 -0400

> should be preferred unless it is nearly impossible to mis-interpret

My personal conviction is that formal languages (e.g. pseudo code) are
less ambiguous than natural languages (e.g. English) in describing
algorithms.  If the intended semantics are that when a protocol
implementation receives a protocol data message with the "foo bit" set
it must return a message to the peer with the "bar bit" set, then pseudo
code is to be preferred.

On the other hand, if we are describing the various and sundry
conditions under which it is desirable or mandatory to set the "foo bit"
in a given protocol data message, then it is likely that natural
languages are preferable.  I think this touches on the discussion of
SHOULD or MUST language.

-- Dave