Version 1.2 of ai12s/ai12-0438-1.txt
!standard 0.2(6) 22-05-05 AI12-0438-1/02
!standard 0.2(8)
!standard 0.2(14/2)
!standard 0.2(33)
!standard 0.2(36)
!standard A.18.2(237.7/5)
!standard A.18.3(151.6/5)
!standard A.18.4(75.7/5)
!standard A.18.7(98.18/5)
!standard A.18.10(218.6/5)
!standard C.7.2(30/2)
!class presentation 22-04-20
!status Amendment 1-2012 22-05-05
!status ARG Approved 14-0-0 22-05-05
!status work item 22-04-20
!status received 22-02-18
!priority Critical
!difficulty Medium
!subject Rewordings to remove "must"
!summary
Several paragraphs needed to be reworded to avoid using "must".
!question
ISO comment #20 says:
Verbal forms used to express provisions in the text do not always comply
with the rules specified in the ISO/IEC Directives, Part 2. Do not use
verbal forms ("could", "might", "need") that are not defined in the
ISO/IEC Directives, Part 2.
Although this comment does not mention "must", it is mentioned in the
directives as a form that should not be used. Should we fix any uses of
"must"? (Yes.)
!recommendation
Replace "must" with "shall" where possible, and reword otherwise. This AI only
contains changes that do not alter the meaning or understandability of the
text. Other changes are found in AI12-0445-1.
!wording
Modify Introduction(6/2):
An Ada program is composed of one or more program units. Program units may
be subprograms (which define executable algorithms), packages (which define
collections of entities), task units (which define concurrent computations),
protected units (which define operations for the coordinated sharing of data
between tasks), or generic units (which define parameterized forms of packages
and subprograms). Each program unit normally consists of two parts: a
specification, containing the information that {is}[must be] visible to
other units, and a body, containing the implementation details, which
{are}[need] not [be] visible to other units. Most program units can be compiled
separately.
[The Introduction is really non-normative material, but that wouldn't allow
anything that could be mistaken as a requirement. Which would make it impossible
to make the point at all. So we'll ignore that distinction here. I'm not sure if
this text needs to appear in the ISO version, so we could eliminate it if the
rewording isn't OK. - Editor]
Modify Introduction(8/2):
An Ada program will normally make use of a library of program units of
general utility. The language provides means whereby individual organizations
can construct their own libraries. All libraries are structured in a
hierarchical manner; this enables the logical decomposition of a subsystem
into individual components. The text of a separately compiled program unit
{has to}[must] name the library units it requires.
Modify Introduction(14/2):
A protected unit is the basic unit for defining protected operations for
the coordinated use of data shared between tasks. Simple mutual exclusion is
provided automatically, and more elaborate sharing protocols can be defined. A
protected operation can either be a subprogram or an entry. A protected entry
specifies a Boolean expression (an entry barrier) that {has to}[must] be True
before the body of the entry is executed. A protected unit may define a single
protected object or a protected type permitting the creation of several similar
objects.
Modify Introduction(33/2):
From any type a new type may be defined by derivation. A type, together
with its derivatives (both direct and indirect) form a derivation class.
Class-wide operations may be defined that accept as a parameter an operand of
any type in a derivation class. For record and private types, the derivatives
may be extensions of the parent type. Types that support these object-oriented
capabilities of class-wide operations and type extension {have to}[must] be
tagged, so that the specific type of an operand within a derivation class can
be identified at run time. When an operation of a tagged type is applied to an
operand whose specific type is not known until run time, implicit dispatching
is performed based on the tag of the operand.
Modify Introduction(36/2):
Aspect clauses can be used to specify the mapping between types and
features of an underlying machine. For example, the user can specify that
objects of a given type {are to}[must] be represented with a given number of bits, or
that the components of a record are to be represented using a given storage
layout. Other features allow the controlled use of low level, nonportable, or
implementation-dependent aspects, including the direct insertion of machine
code.
Modify A.18.2(237.7/5):
If a stable vector is declared without specifying Base, the object
{has to}[must] be initialized. The initializing expression of the stable vector,
typically a call on To_Vector or Copy, determines the Length of the vector.
The Length of a stable vector never changes after initialization.
{AARM Proof: Initialization is required as the type is indefinite, see 3.3.1.}
Modify A.18.3(151.6/5):
If a stable list is declared without specifying Base, the object {has to}[must]
be initialized. The initializing expression of the stable list, typically a
call on Copy, determines the Length of the list. The Length of a stable list
never changes after initialization.
{AARM Proof: Initialization is required as the type is indefinite, see 3.3.1.}
Modify A.18.4(75.6/5):
If a stable map is declared without specifying Base, the object {has to}[must]
be initialized. The initializing expression of the stable map, typically a call
on Copy, determines the Length of the map. The Length of a stable map never
changes after initialization.
{AARM Proof: Initialization is required as the type is indefinite, see 3.3.1.}
Modify A.18.7(98.18/5):
If a stable set is declared without specifying Base, the object {has to}[must]
be initialized. The initializing expression of the stable set, typically a
call on Copy, determines the Length of the set. The Length of a stable set
never changes after initialization.
{AARM Proof: Initialization is required as the type is indefinite, see 3.3.1.}
Modify A.18.10(218.6/5):
If a stable tree is declared without specifying Base, the object {has to}[must]
be initialized. The initializing expression of the stable tree, typically a
call on Copy, determines the Node_Count of the tree. The Node_Count of a
stable tree never changes after initialization.
{AARM Proof: Initialization is required as the type is indefinite, see 3.3.1.}
Modify C.7.2(30/2):
Some implementations are targeted to domains in which memory use at run
time {has to}[must] be completely deterministic. For such implementations, it is
recommended that the storage for task attributes will be pre-allocated
statically and not from the heap. This can be accomplished by either placing
restrictions on the number and the size of the attributes of a task, or by
using the pre-allocated storage for the first N attribute objects, and the
heap for the others. In the latter case, N should be documented.
!discussion
To summarize the relevant ISO rules from the Directives part 2:
Requirements use "shall" preferably, or phrases involving forms of "require",
"has to", or "it is necessary". "Must" is not allowed (it can be
used for external requirements, such as government laws, but that usually
doesn't apply to us).
Other forms are not allowed to express requirements. The ISO House Rules
document goes further and bans a number of other words completely. More on
this topic can be found in AI12-0445-1.
---
We could consider making wording changes only for the ISO version (new
commands would be needed in the formatter to support that if is done a lot
- currently, we can only do that on a full paragraph basis or with a few
macros - but new commands should not be hard to define and implement).
However, that would add complications to future maintenance (as we would need
to somehow have both versions in any Corrigendum document, one for our use and
one for the actual ISO Corrigendum). As such, we want to make any changes that
do not clearly alter the meaning or harm the understandability of the text.
!ASIS
No ASIS effect.
!ACATS test
No ACATS test should be needed, no change in meaning is intended and these
are notes anyway.
!appendix
****************************************************************
Questions? Ask the ACAA Technical Agent