From 8080a8d545fd7265fc7ba445b02181ead8360d20 Mon Sep 17 00:00:00 2001 From: Pat Rogers Date: Fri, 19 Sep 2025 11:57:19 -0500 Subject: [PATCH] Make terminology consistent. Change left-over usage of "solution" to "implementation" so that we use "implementation" consistently throughout the course. --- .../chapters/abstract_data_types.rst | 3 +-- .../ada-in-practice/chapters/introduction.rst | 8 ++++---- .../courses/ada-in-practice/chapters/raii.rst | 6 +++--- .../chapters/streams_api_flexibility.rst | 16 ++++++++-------- 4 files changed, 16 insertions(+), 17 deletions(-) diff --git a/content/courses/ada-in-practice/chapters/abstract_data_types.rst b/content/courses/ada-in-practice/chapters/abstract_data_types.rst index 40de12c5c..1943749bc 100644 --- a/content/courses/ada-in-practice/chapters/abstract_data_types.rst +++ b/content/courses/ada-in-practice/chapters/abstract_data_types.rst @@ -345,8 +345,7 @@ fundamental to creating abstractions in class-oriented languages. Not every type can be private, as illustrated by the client expectation for array indexing in Ada prior to Ada 2012. Not every type should be private, for example those that are -explicitly numeric. But the ADT should be the default design idiom when -composing a solution. +explicitly numeric. But the ADT should be the default design idiom expression. Cons ---- diff --git a/content/courses/ada-in-practice/chapters/introduction.rst b/content/courses/ada-in-practice/chapters/introduction.rst index 95c7fb581..0f17c99b3 100644 --- a/content/courses/ada-in-practice/chapters/introduction.rst +++ b/content/courses/ada-in-practice/chapters/introduction.rst @@ -32,7 +32,7 @@ Likewise, :wikipedia:`Resource Acquisition Is Allocation (RAII) :wikipedia:`implementation inheritance ` are not design patterns. -Those are the kinds of situations and solutions we focus upon. +Those are the kinds of situations and implementations we focus upon. That said, we may refer to a design pattern to illustrate an idiom's purpose and/or implementation. For example, in the idiom for controlling @@ -40,7 +40,7 @@ object creation and initialization, the implementation approach happens to be the same as for expressing a Singleton :footcite:p:`1995:gamma`. In addition to language-independent situations, we also include -solutions for situations specific to the Ada language. These idioms are +implementations for situations specific to the Ada language. These idioms are *best practices* in situations that arise given the extensive capabilities of the language. @@ -59,7 +59,7 @@ These are the well-known Abstract Data Types, something the Ada language directly supports but using *building blocks* instead of a single construct. For that same reason we include another idiom for defining abstractions that manage global data (Abstract Data Machines). Most of -the idioms' solutions will be defined using these abstraction techniques +the idioms' implementations will be defined using these abstraction techniques as their starting point. @@ -67,7 +67,7 @@ Assumptions ----------- We assume the reader knows Ada to some degree, including some advanced topics. -For those lacking significant familiarity, we hope these solutions will at +For those lacking significant familiarity, we hope these implementations will at least give a sense for how to apply the language. We direct such readers to the :ref:`online Learn courses dedicated to the Ada language itself `. diff --git a/content/courses/ada-in-practice/chapters/raii.rst b/content/courses/ada-in-practice/chapters/raii.rst index 488dfc556..c2ecd36f8 100644 --- a/content/courses/ada-in-practice/chapters/raii.rst +++ b/content/courses/ada-in-practice/chapters/raii.rst @@ -235,10 +235,10 @@ important here, but we must set them all if we set any of them. This design works, but the resulting code is clearly more complex and less robust than the PO approach. -Solution --------- +Implementation +-------------- -Our solution uses an explicit global lock (a mutex), as above, but reintroduces +Our implementation uses an explicit global lock (a mutex), as above, but reintroduces automatic lock acquisition and release. To achieve that automation, we leverage the language-defined object *lifetime* diff --git a/content/courses/ada-in-practice/chapters/streams_api_flexibility.rst b/content/courses/ada-in-practice/chapters/streams_api_flexibility.rst index e37386733..ccacd39d6 100644 --- a/content/courses/ada-in-practice/chapters/streams_api_flexibility.rst +++ b/content/courses/ada-in-practice/chapters/streams_api_flexibility.rst @@ -43,8 +43,8 @@ that the compiler can catch our mistakes. After all, preventing coding errors is much cheaper than fixing them later. -Solution --------- +Implementation +-------------- We will explore the possibilities using a concrete :wikipedia:`USART (Universal Synchronous/Asynchronous Receiver Transmitter) ` @@ -86,10 +86,10 @@ Note the formal parameter data type for both :ada:`Receive` and might actually want to send and receive such values directly, that's probably not the case. -Our solution is structured as a package hierarchy rooted at package -:ada:`Serial_IO`. (This solution is part of an example in the ADL |mdash| see +Our implementation is structured as a package hierarchy rooted at package +:ada:`Serial_IO`. (This implementation is part of an example in the ADL |mdash| see :ref:`Note #1 ` below.) This root -package declares a record type and routines that are common to any solution. +package declares a record type and routines that are common to any implementation. The type, named :ada:`Peripheral_Descriptor`, contains a component named :ada:`Transceiver` that will designate the actual on-chip USART device being driven. The other record components are required for connecting that device to @@ -137,7 +137,7 @@ parameters. Clients will call these procedures directly to set up the STM32 on-chip USART device. -Our solution will consist of an ADT named :ada:`Serial_Port`, and a means for +Our implementation will consist of an ADT named :ada:`Serial_Port`, and a means for sending and receiving values of higher-level types via :ada:`Serial_Port` objects. Type :ada:`Serial_Port` will be a wrapper for the device driver's USART type. Therefore, the type :ada:`Serial_Port` will have an access @@ -595,8 +595,8 @@ inside the package body. Furthermore, the approach is independent of other design considerations, such as whether callers wait for completion of the invoked I/O operation. -Because it is maximally flexible and concise, we consider it the best solution -to this idiom. The generic-based approach remains a good one, however. +Because it is maximally flexible and concise, we consider it the best implementation +for this idiom. The generic-based approach remains a good one, however. .. _Ada_In_Practice_Using Streams_Cons: