AI22-0055-1

!standard 3.9(27/5)                                        23-05-19  AI22-0055-1/03

!standard 4.6(62)

!standard 7.6.1(24)

!standard 9.8(22/5)

!standard 9.9(7/5)

!standard 9.9(8/5)

!standard 11.4.2(28/5)

!standard 12.4(12)

!standard 12.6(12)

!standard 13.9.2(14/5)

!standard A.5.2(50/5)

!standard A.16(131/5)

!standard B.3.2(43)

!standard C.3.1(23/5)

!standard D.13(12/5)

!class binding interpretation 22-11-30

!status work item 22-11-30

!status received 22-11-04

!priority Low

!difficulty Easy

!qualifier Correction

!subject Usage Advice

!summary

Move certain NOTEs and all examples into a new “Usage” section, replacing the separate “Examples" section.

!issue

Various notes in the Standard provide advice to the Ada user. These notes use wording like "should", "recommended", or "preferred". None of these wordings are allowed in notes.

We need a different approach for handling advice on writing Ada programs.

!recommendation

(See Summary.)

!wording

[Editor's note: I've included some usage notes whose rewording late in the Ada 2022 process were not rejected. These still were originally intended to be usage advice, and should be handled accordingly in future Ada standards. However, they remain in the FDIS and RM as reworded. All of these are marked "was not flagged".]

Modify 1.1.2(39):

[Examples]{Usage}

Usage can include advice to the programmer, and examples that illustrate the possible forms of the constructs described. Individual examples are informative.

[Editor’s note: Examples have a required style in the ISO documents, so this would have to be treated somewhat differently in the ISO Standard. Additionally, the “Examples” category includes a defined format even the the RM, so removing it completely would have some side-effects. We need to be careful to not cause a lot of work in RM reformatting.]

Modify 3.9(27/5):

{Usage}

[NOTE 1  ]A type declared with the reserved word tagged is normally declared in a package_specification, so that new primitive subprograms can be declared for it.

[This was not flagged; but the original wording used "should normally be declared" and even now it still reads as a recommendation. The original wording is better and should be used when this is moved to a new category.]

Modify 4.6(62):

{Usage}

[NOTE 3   ]The constraint of the target subtype has no effect for a type_conversion of an elementary type passed as an out parameter. Hence, it is recommended that the first subtype be specified as the target to minimize confusion (a similar recommendation applies to renaming and generic formal in out objects).

["it is recommended that"; this is "Usage Advice". A rewrite would lose the point. The Editor would recommend explaining which "first subtype" is being recommended in this note; there are a lot of first subtypes in an Ada program. (It's likely intended to be "the first subtype of the elementary type", or should that be "an elementary type"? 12.4 uses "a first subtype" for a similar note, that's vague but still better than a mysterious particular first subtype.)]

Modify 7.6.1(24):

{Usage}

[NOTE 4   ]The Finalize procedure is called upon finalization of a controlled object, even if Finalize was called earlier, either explicitly or as part of an assignment; hence, if a controlled type is visibly controlled (implying that its Finalize primitive is directly callable), or is nonlimited (implying that assignment is allowed), its Finalize procedure is ideally designed to have no ill effect if it is applied a second time to the same object.

[This was not flagged; but the original wording used "should be" instead of "is ideally" and it still reads as a weak recommendation. The original wording is better and should be used when this is moved to a new category.]

Modify 9.8(22/5):

{Usage}

[NOTE 1   ]An abort_statement is best used only in situations requiring unconditional termination.

[This was not flagged; but the original wording used "should be" instead of "is best" and it still reads as a weak recommendation. The original wording is better and should be used when this is moved to a new category.]

Modify 9.9(7/5, 8/5):

{Usage}

[NOTE 2   ]Within task units, algorithms interrogating the attribute E'Count should take precautions to allow for the increase of the value of this attribute for incoming entry calls, and its decrease, for example with timed_entry_calls. Also, a conditional_entry_call can briefly increase this value, even if the conditional call is not accepted.

[The rewording was not flagged, but it rather lost the point, and the original wording given here is clearly a usage recommendation.]

[NOTE 3   ]Within protected units, by interrogating the attribute E'Count in the entry_barrier for the entry E should take precautions to allow for the evaluation of the condition of the barrier both before and after queuing a given caller.

[The rewording was not flagged, but it rather lost the point, and the original wording given here is clearly a usage recommendation.]

Modify 11.4.2(28/5):

{Usage}

[NOTE   Normally, the]{The} boolean expression in a pragma Assert should not call functions that have significant side effects when the result of the expression is True, so that the particular assertion policy in effect will not affect normal operation of the program.

["should"; this is clearly a usage recommendation. The "Normally" seems unneeded in a statement that is already advice rather than a command -- one only needs a single weasel word.]

Modify 12.4(12):

{Usage}

[NOTE   ]The constraints that apply to a generic formal object of mode in out are those of the corresponding generic actual parameter (not those implied by the subtype_mark that appears in the formal_object_declaration). Therefore, to avoid confusion, it is recommended that the name of a first subtype be used for the declaration of such a formal object.

["it is recommended that". The last sentence here is "usage advice" (see above). Rewriting probably will not keep the point.]

Modify 12.6(12):

{Usage}

[NOTE 2   ]The constraints that apply to a parameter of a formal subprogram are those of the corresponding formal parameter of the matching actual subprogram (not those implied by the corresponding subtype_mark in the _specification of the formal subprogram). A similar remark applies to the result of a function. Therefore, to avoid confusion, it is recommended that the name of a first subtype be used in any declaration of a formal subprogram.

["it is recommended that". Usage advice.]

Modify 13.9.2(14/5):

{Usage}

[NOTE 3   ]The Valid attribute can be used to check the result of calling an instance of Unchecked_Conversion (or any other operation that can return invalid values). However, an exception handler should also be provided because implementations are permitted to raise Constraint_Error or Program_Error if they detect the use of an invalid representation (see 13.9.1).

[The second sentence (original wording here) is clearly a usage recommendation; the rewording of "is still useful" wasn't flagged but still is a weak recommendation. The original wording is better and should be used when this is moved to a new category.]

Modify A.5.2(50/5):

{Usage}

[NOTE 3   ]A given implementation of the Random function in Numerics.Float_Random is not guaranteed to be capable of delivering the values 0.0 or 1.0. Applications will be more portable if they assume that these values, or values sufficiently close to them to behave indistinguishably from them, can occur. If a sequence of random integers from some range is necessary, it is preferred that the application uses one of the Random functions in an appropriate instantiation of         Numerics.Discrete_Random, rather than transforming the result of the Random function in Numerics.Float_Random.

["it is preferred", with the following comment: "Preferred by whom? If this is a covert recommendation, please rephrase so it expresses a statement of fact." This is clearly a usage recommendation, and the note makes little sense as a "statement of fact". We have partially reverted this wording for Ada 2022 to:

NOTE 3   A given implementation of the Random function in Numerics.Float_Random is not guaranteed to be capable of delivering the values 0.0 or 1.0. Applications will be more portable if they that these values, or values sufficiently close to them to behave indistinguishably from them, can occur. If a sequence of random integers from some range is necessary, the application should use one of the Random functions in an appropriate instantiation of Numerics.Discrete_Random, rather than transforming the result of the Random function in Numerics.Float_Random.

which makes the meaning clearer. Note that the original wording also used "Portable applications should assume", but it is not as clear that is an improvement over the rewording, so it was not changed.

The following note gives advice on creating exponentially distributed values. This note also was removed from the Ada 2022 Standard as it doesn't make a lot of sense without the preceding note. It also should be handled as Usage Advice.]

Modify A.16(131/5):

{Usage}

[NOTE 5   ]To move a file or directory to a different location, use Rename.  Most target systems will allow renaming of files from one directory to  another. If the target file or directory can already exist, delete it first.

["delete it first" was highlighted here, without comment. Not sure what the complaint is. Ada 2022 reverted this to the original wording of "it should be deleted first", which makes t clear usage advice.]

Modify B.3.2(43):

{Usage}

[NOTE   ]To compose a Pointer from an Element_Array, use 'Access on the first element. For example (assuming appropriate instantiations):

["use" is highlighted here without comment. Not sure what is wrong here, but this is again (weak) usage advice.]

Modify C.3.1(23/5):

{Usage}

[NOTE 2  ] For a protected object that has a (protected) procedure attached to an interrupt, the correct ceiling priority is at least as high as the highest processor priority at which that interrupt will ever be delivered.

[Not flagged, this was reworded to remove "should", but it still is clearly a usage recommendation.]

Modify D.13(12/5):

{Usage}

[NOTE 3   ]It is not recommended to specify the CPU of a task to be Not_A_Specific_CPU when the Ravenscar or Jorvik profile is in effect. How a partition executes strongly depends on the assignment of tasks to CPUs.

["it is not recommended". This is usage advice.]

!discussion

The Ada Reference Manual (RM) has reserved normative recommendations to apply only to implementers (that is, the people who are attempting to build an Ada processor that conforms to the Standard). Words like "should" and "it is recommended" are always interpreted to apply to implementers.

In order to provide advice on using the Ada language, a number of notes (which are considered non-normative) are included in the RM. These also use words like "should" and "it is recommended" but are clearly not intended to be part of the Standard.

Unfortunately, the "JTC1 Directives, Part 2" (the document which gives the rules for drafting JTC1 standards), no longer allows requirements or recommendations to be given in notes. All of the notes that give usage advice clearly violate this rule, and cannot be reworded to avoid the restrictions without eliminating the advice that they are intended to give. We need to do something about this.

The "Directives" suggest that a Standard be aimed at a single audience, and that other standards (or parts of standards) be produced for other audiences. That would suggest creating an additional part specifically to give usage advice. However, doing that would either end up with a *very* skinny document, or would require a lot of additional work to define style recommendations to flesh out the document. This does not seem to be a topic on which to expend scarce resources.

If we want to continue to have the notes in the RM (and Standard), then we need to move them to the body of the RM. To do that, we would need to define a category subheading ("Usage" is what is recommended here). Then we can use wording like "should" with the audience clearly indicated. We also recommend that we also create an Annex that summarizes that advice in one place (much as we do for Implementation Advice), with an introduction of

something like "This annex summarizes the advice given for the usage of the Ada language in this document."

A third alternative would be to simply put all of these notes into a dedicated Annex. That would meet the directives. However, it would mean that the usage information would be far away from the definition of a feature. It seems unlikely that someone reading about the random number package would remember to look in the Usage Advice annex to see if there was anything relevant (especially as there often would not be any advice).

A fourth alternative would be to remove these notes permanently from the RM, and simply move them to the AARM in a new category "Usage". That could be indexed so that users can find it. However, the AARM is aimed at implementers and language lawyers, not ordinary users. So doing this would mean that the notes would not be seen by the intended audience.

[Editor's note: For the purposes of the Ada 2022 Standard, we just deleted the offending notes, leaving the RM alone. It was too late to make a major restructuring of the standard (adding new subheadings, normative wording, and an Annex). When it says above that a note was reverted in Ada 2022, it means in the Ada 2022 RM (such notes do not appear in the Ada 2022 Standard).]

** TBD: Discussion topics for an ARG meeting:

We first need to decide if we want to follow the recommendation of adding a new category, or whether we would prefer to follow one of the other options (a new part, a new Annex only, or making these only AARM notes).

Assuming we follow the recommendation given here, we should consider whether we want a "Usage" category or some other term. Many of the existing notes are really about usage, including things that are not allowed (and thus have to be avoided). [Note: "Usage note" was also suggested, but that could be confused with an actual "Note". These cannot be any kind of note, given the Directives.]

Once we've picked a category name, a victim, er volunteer needs to read all of the existing notes (in the entire RM) and determine if there are others that should be moved to this new category. We shouldn't determine the contents of a category by ISO editorial objections (and all of the notes in the current version of this AI were objected to by ISO at some point).. Someone also needs to look at the notes given here and any additional notes in this new category to check that the wording would be acceptable as normative wording. (Sloppy wording - such as that which is not always true - can appear in notes, but not in the normative part of the RM.)

** End TBD.

!ACATS test

None needed, this is not intended to be testable text (even if included in the text of the RM).

!appendix