GNU Algol 68 Coding Guidelines - V3 possible inconsistencies and errata?

[Jose E. Marchesi]

Hi Chris.

As always thank you for the feedback.

> Good afternoon everyone,
>
> I may be making a bad decision here and if so PLEASE feel free to chastise
> me.
>
> I see the odd minor thing in Jose's excellent Coding Guidelines and I have
> chosen to report them here rather than inserting a single line in the midst
> of hundreds of lines of quote text.
>
> 1. missing? I see declarations such as "[]int" but I don't see a rule about
> spacing in row declarations - or is this covered by "Spaces in
> bounds"?

Yeah there is no rule for that.  I am turning the `Spaces in bounds'
section into the more general `Spaces in declarers'.

> 2. consistency? I read "But make sure to always put a space between `union'
> or `struct' and
> the open parenthesis that follows in declarers" - are these the only times
> spaces are allowed in declarers? Otherwise I'm confused as to why we are
> requiring "struct (int a,real b) foo" but "proc(int,real)void" - in a
> parameter pack with a struct do we code it as "struct(int a,real b)foo"?

Yes indeed that is an inconsistency.

In a sense, union(..) and struct(..) have the same "shape" than a
function call.  Using a space helps to distinguish them.  proc(...)xxx
and op(...)yyy have a different shape...

Dunno, perhaps we should also use struct(..) and union(..) without
space.  But somehow I don't like the idea.

> 3. erratum?  I see "op(intint)int handler;" but think it should be
> "op(int,int)int handler;"

Fixed.

> 4. erratum?  I see "json_foreach_elem(a, (ref JSON_Val v) void: len +:= 1)"
> but I feel that this should maybe be "json_foreach_elem(a, ref JSON_Val v)
> void: (len +:= 1)" or maybe something else entirely

The second argument to the routine json_foreach_elem is a routine text

  (ref JSON_Val v) void: len +:= 1


> 5. wrong place? There is a paragraph in "Spaces in indexers and trimmers"
> that indicates preference for [ and ] rather than ( and ); I think this
> paragraph should have its own section, or maybe be combined with a section
> on preferred orthography.

I moved that paragraph into a new subsection within "Syntactic
Conventions".


> 6. suggestion for improvement? This sentence:
>
> In little local auxiliary routines, do not add arguments just to pass a
>> value thas is in the environment, unless the declaration of the later is
>> very far away from the routine text: make the routine access the value
>> itself.
>
>
> Here "thas" should be "that" and "later" should be "latter".
>
> But my main point is "very far away" - let me describe a hypothetical
> situation:
> - 17 ref int, ref real and ref string are declared
> - "further along" a "little local auxiliary routine" is declared that reads
> 9 of these values and alters 3 more
>
> If this is really necessary, in my view the auxiliary routine should be
> declared right next to the 17 ref int etc values so that it is clear to the
> maintainer that the purpose of the auxiliary routine is to manipulate these
> values thoroughly, rather than declare the auxiliary routine near where it
> is called.
>
> So I would advocate for the paragraph to be more along the lines of:
>
> In little local auxiliary routines, do not add arguments just to pass a
> value that is in the environment; rather, place the declaration of the
> auxiliary routine near the declarations of the values it accesses.  If this
> is not possible, then it may be wise to judiciously pass those non-nearby
> values as arguments in order that the programmer be aware that non-nearby
> values are being accessed or possibly altered.

Your paragraph is much better.  I replaced the existing one with it.

Thanks!