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

From: Wes Hardaker <[email-masked]>
Date: Mon, 06 Sep 2004 21:10:41 -0700

In revising the SBSM draft over time I've considered many ways to
document the elements of procedures required to implement the
protocol.  Initially I started out writing everything in text, but in
the last document I switched some of the simpler assignment type
actions to simple equations since I think it's much more concise and
harder to mis-read [there is a section that documents that both text
and equations MUST be followed for the protocol implementation to be
complete].  But lately, I'm thinking that stream-lining things even
more would actually improve the document.  Right now, its fairly
lengthy in large part due to the sentence-text required to document
how to do particular things, when pseudo-code could be quite a bit
shorter.

So, let me give me some examples of the same way to say something and
ask which people would prefer.

  a) all english text for more complex decisions:

    * If the current time minus the session.startTime is
    greater than the number of seconds from the
    session.legalSessionLength field (or any other value from
    a policy that restricts session time lengths), then the
    session MUST be immediately closed (see Section <xref
    target="closed"/> for information on closing a session)
    and an unknownSBSMSession error returned to the calling
    module.

  b) all pseudo-code:

    if (current_time - session.startTime > session.legalSessionLength) {
       session.status = CLOSED;
       return unknownSBSMSession;
    }

  c) pseudo-code with a introductory bullet:

    * Check the session for whether it should be expired or not:

    if (current_time - session.startTime > session.legalSessionLength) {
       session.status = CLOSED;
       return unknownSBSMSession;
    }

  d) pseudo-code with a introductory pseudo-code comment:

    /* Check the session for whether it should be expired or not: */
    if (current_time - session.startTime > session.legalSessionLength) {
       session.status = CLOSED;
       return unknownSBSMSession;
    }

The end result is that I am now leaning toward (c).  Does anyone else
have preferences for style that they'd prefer to read?  Currently, the
pseudo-code statements I have in there are very simple assignments
without things like the above if() type clauses.

[FYI, to see the current introductory text see the section entitled
"Protocol documentation conventions" in the full document].

-- 
Wes Hardaker
Sparta

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

---

From: Robert Story <[email-masked]>
Date: Tue, 7 Sep 2004 10:35:35 -0400

On Mon, 06 Sep 2004 21:10:41 -0700 Wes wrote:
WH> The end result is that I am now leaning toward (c).  Does anyone else
WH> have preferences for style that they'd prefer to read?  Currently, the
WH> pseudo-code statements I have in there are very simple assignments
WH> without things like the above if() type clauses.

If the text preceding the pseudo-code explains what is going on, then b-d are
pretty much equivalent.

My initial reaction was d, but now I'm wonder if a+b isn't better. You didn't
include the text that would have been above the examples. My concern is that if
I read just a or just b, I don't know that I would have came to the same
understanding. In particular:

WH>        session.status = CLOSED;

simply sets a flag, whereas

WH>     * If [session expired], then the session MUST be immediately closed

would have ended up in my code as

	session_close(close);

If the text preceding the example were sufficiently clear on the closing of the
session, the I suppose any of b-d would be fine.

-- 
Robert Story; NET-SNMP Junkie
<irc://irc.freenode.net/#net-snmp>   <http://www.net-snmp.org/>

You are lost in a twisty maze of little standards, all different.

---

From: Wes Hardaker <[email-masked]>
Date: Tue, 07 Sep 2004 07:43:08 -0700

>>>>> On Tue, 7 Sep 2004 10:35:35 -0400, Robert Story <[email-masked]> said:

Robert> If the text preceding the pseudo-code explains what is going
Robert> on, then b-d are pretty much equivalent.

The intent was to drop the text if the pseudo-code could be made
sufficiently clear.

Robert> simply sets a flag, whereas

WH> * If [session expired], then the session MUST be immediately
WH>   closed

What wasn't shown in the example was preceding text early on that
explained the different states with the status value, etc.

And actually, the way the EoP is structured setting the above flag
would work just fine.

Robert> would have ended up in my code as

Robert> session_close(close);

Entirely deleting the session actually isn't desired as its supposed
to stay around for 5 minutes or so and just be closed.  Hence a flag
is actually closer to the correct interpretation.

-- 
Wes Hardaker
Sparta

---

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

Hi,

I think the example is a good one.

"session.status = CLOSED;" does not convey the MUST keyword. 
Pure pseudo-code seems inadeqaute for expressing MUST/SHOULD/MAY
behaviors needed for a standard.

I recommend text plus psuedo-code. I don't much care about whether the
text is contained in plain text, or in pseudocode comments as long as
it is made clear what behavior is required, without ambiguity. 

A mix of the styles would also be fine by me, chosen to best meet the
specific situation; if there is no MUST/SHOULD/MAY to convey, I don't
see any reason not to use a pseudocode comment.

David Harrington
[email-masked]

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

Robert> If the text preceding the pseudo-code explains what is going
on, 
Robert> then b-d are pretty much equivalent.

--
Wes Hardaker
Sparta

---

From: Ken Hornstein <[email-masked]>
Date: Tue, 07 Sep 2004 12:19:06 -0400

Just my $0.02, I find _this_

>       return unknownSBSMSession;

As a programmer, I find this simple and elegant.  I can think of a
number of cases in IETF standards where the explanatory text was
misunderstood upon reading, but I don't think this would be
misunderstood.  One other standard that took a more program-like
description of the protocol (I am thinking of IrDA, which descripted a
FSM along with the English text) helped to explain a lot of the more
confusing parts.

So I think I'm leaning toward (c) or (d), but maybe with two or three
sentences as opposed to one (ideally, you'd put the whole paragraph in
there, but in addition to being redundant, I'm sure you don't have
infinte time :-) )

--Ken

---

From: Dinakaran Joseph <[email-masked]>
Date: Tue, 7 Sep 2004 11:19:46 -0600

Hi Wes,

As a programmer, I find it much easier to read the psuedo-code rather than 
the text. Having said that, I would also agree with Dave that there needs 
to be a way to specify MUST/MAY/SHOULD that the psuedo-code method does 
not provide. (c) or (d) would be a great way to document the elements of 
procedure. The comment could specify the MUST/MAY/SHOULD aspect of what 
needs to happen along with the pseudo-code, if possible.

/Dinakaran.

---

From: "Wayne Kading" <[email-masked]>
Date: Wed, 8 Sep 2004 15:32:14 -0500

Wes,

I agree with the following comment from Joseph.  I believe it would also
have been important to note in the comment text for the 'c' and 'd' examples
that the MUST aspect also applies to the returned error code.

Wayne

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On
Behalf Of Dinakaran Joseph
Sent: Tuesday, September 07, 2004 12:20 PM
To: Wes Hardaker
Cc: [email-masked]
Subject: Re: [Isms] documentation style for SBSM: pseudo-code vs text

Hi Wes, 

As a programmer, I find it much easier to read the psuedo-code rather than
the text. Having said that, I would also agree with Dave that there needs to
be a way to specify MUST/MAY/SHOULD that the psuedo-code method does not
provide. (c) or (d) would be a great way to document the elements of
procedure. The comment could specify the MUST/MAY/SHOULD aspect of what
needs to happen along with the pseudo-code, if possible. 

/Dinakaran.

---

From: Wes Hardaker <[email-masked]>
Date: Wed, 08 Sep 2004 14:13:49 -0700

>>>>> On Wed, 8 Sep 2004 15:32:14 -0500, "Wayne Kading" <[email-masked]> said:

Wayne> I agree with the following comment from Joseph.  I believe it
Wayne> would also have been important to note in the comment text for
Wayne> the 'c' and 'd' examples that the MUST aspect also applies to
Wayne> the returned error code.

Ok, it is clear from the last few messages that pseudo-code is
preferred when the intent (and requirements to implement it) can be
made clear.  I'll endeavor to do that as I revise it.  Thanks for all
the input.

-- 
Wes Hardaker
Sparta