Improvements to language.

Author: dhebbeker

doc/decisions/dr-004.md

@@ -1,67 +1,67 @@
-# DR004 Direct usage of Hardware Abstraction Layer
+# DR004 Direct Usage of Hardware Abstraction Layer
 
 ## Context
 
-Currently we violate the requirement to use libraries and frameworks only through adapters, as it is required by the objectives of the software architecture (see 
-[relevant section in Software Architecture](<\ref flexible_structure> "relevant section in Software Architecture")):
-We currently use an implementation of the [ArduinoCore-API][ACA] (ACA) as a hardware abstraction layer (HAL) from outside of the adapters layer.
-More specifically we use an implementation of the ACA from Espressif coined for ESP32s.
+Currently, we are in violation of the requirement to only use libraries and frameworks through adapters, as mandated by the objectives of the software architecture (see 
+[relevant section in Software Architecture](<\ref flexible_structure> "relevant section in Software Architecture")).
+Currently, we utilize an implementation of the [ArduinoCore-API][ACA] (ACA) as a hardware abstraction layer (HAL) from outside the adapters layer.
+More specifically, we employ an implementation of the ACA from Espressif, tailored for ESP32s.
 
-It is generally assumed that using HALs is only necessary from the
+It is generally understood that using HALs is only necessary from the
 [board adapters package](<\ref board_adapters> "board adapters package").
 
 [ACA]: https://github.com/arduino/ArduinoCore-API
 
 ## Options
 
-There are several options on how to resolve this violation of our own rules.
+There are several options for resolving this violation of our own rules.
 
 ### Option 1
 
-Abide to the current guidelines.
+Adhere to the current guidelines.
 
-According to the current state of the software architecture we should use the 3rd party HAL indirectly through adapters.
-Those adapters would reside in the 
+According to the current state of the software architecture, we should use the 3rd party HAL indirectly through adapters.
+These adapters would reside in the
 [3rd party adapters package](<\ref third_party_adapters> "3rd party adapters package").
 
 #### Option 1a)
 
-For an object oriented (OO) variant, defining an interface and inheriting from it would require to:
+For an object-oriented (OO) variant, defining an interface and inheriting from it would require:
 
-- define one or several interfaces inside the
+- Defining one or several interfaces inside the
   [board adapters package](<\ref board_adapters> "board adapters package")
-  (header files)
-- implement those as adapters inside the
+  (header files).
+- Implementing those as adapters inside the
   [3rd party adapters package](<\ref third_party_adapters> "3rd party adapters package")
-  (source files)
-- define interfaces for the factories (see 
+  (source files).
+- Defining interfaces for the factories (see 
   [dependency injection](<\ref dependency_injection> "dependency injection"))
   inside the
   [board adapters package](<\ref board_adapters> "board adapters package")
-  (header files)
-- implement those factories inside the
+  (header files).
+- Implementing those factories inside the
   [3rd party adapters package](<\ref third_party_adapters> "3rd party adapters package")
-  (source files)
+  (source files).
 
-This is the usual way dependency injection and therefore the 
-[dependency rule](<\ref interpretation_dependency_rule> "dependency rule")
+This is the typical way dependency injection, and therefore the 
+[dependency rule](<\ref interpretation_dependency_rule> "dependency rule"),
 is implemented.
 
 #### Option 1b)
 
-Instead of using an object oriented approach using inheritance, one could create an interface to the HAL based on free functions.
+Instead of using an object-oriented approach using inheritance, one could create an interface to the HAL based on free functions.
 
-This option would require to:
+This option would require:
 
-- define one or several interfaces (free function declarations) inside the
+- Defining one or several interfaces (free function declarations) inside the
   [board adapters package](<\ref board_adapters> "board adapters package")
-  (header files)
-- implement those as adapters inside the
+  (header files).
+- Implementing those as adapters inside the
   [3rd party adapters package](<\ref third_party_adapters> "3rd party adapters package")
-  (source files)
-- if the build configuration (see [`lib_ldf_mode`][1]) requires it, one may have to define 
+  (source files).
+- If the build configuration (see [`lib_ldf_mode`][1]) requires it, one may have to define
   [proxy headers](<\ref proxy_header> "proxy headers")
-  (header files)
+  (header files).
 
 Factories are not necessary because this approach does not rely on objects.
 
@@ -70,110 +70,109 @@ Factories are not necessary because this approach does not rely on objects.
 #### Option 1c)
 
 A hybrid approach (OO and free functions) is also possible.
-This would fit well to the ACA as is also consists of classes and free functions.
+This would fit well with the ACA as it also consists of classes and free functions.
 
-The steps required would be a mixture of those of options 1a) and 1b).
+The required steps would be a mixture of those of options 1a) and 1b).
 
 ### Option 2
 
-Change the current guidelines such that the direct dependency to 3rd party HALs is allowed within hardware related packages (which is currently only the 
+Change the current guidelines so that direct dependency on 3rd party HALs is allowed within hardware-related packages (currently only the
 [board adapters package](<\ref board_adapters> "board adapters package")).
 
-This approach eliminates the requirement to define 3rd party adapters to the HAL.
+This approach eliminates the requirement to define 3rd party adapters for the HAL.
 
-In order to be able to test code depending on the ACA, the 3rd party interface needs to be stubbed.
+In order to test code depending on the ACA, the 3rd party interface needs to be stubbed.
 *For vanilla ACA, stubbing the proprietary interface can be greatly simplified by using [ArduinoFake][].*
-We use an [implementation of the Arduino Core API (ACA) specific for ESP32s by Espressif](https://github.com/espressif/arduino-esp32/) which extends the ACA.
-Following the approach of this option, to directly use ACA and ArduinoFake for testing, we would need to deal with the extensions separately.
-The following variants of this option, specifies different methods to cope with the extensions.
+We utilize an [implementation of the Arduino Core API (ACA) specific for ESP32s by Espressif](https://github.com/espressif/arduino-esp32/) which extends the ACA.
+Following this option's approach, to directly use ACA and ArduinoFake for testing, we would need to manage the extensions separately.
+The following variants of this option specify different methods to handle the extensions.
 
 [ArduinoFake]: https://platformio.org/lib/show/1689/ArduinoFake "ArduinoFake in PlaftormIO's registry"
 
 #### Option 2a)
 
 Instead of directly using a modified Arduino interface provided by the extensions (for example for a specific `class`), we use an adapter.
 The adapters would be integrated just as for option 1.
-But compared to option 1 this only needs to be done for those smallest indivisible interfaces which are not compatible to the vanilla ACA.
+But compared to option 1, this only needs to be done for those smallest indivisible interfaces which are not compatible with the vanilla ACA.
 
 #### Option 2b)
 
 At those places in the source code where extensions are used, we introduce conditionally compiled sections.
 One section uses the modified version of the ACA, necessary for the productive code.
-The alternative section is instead used when compiling for native tests.
+The alternative section is used when compiling for native tests.
 It uses the vanilla ACA which can be simply stubbed using ArduinoFake.
 
 The selection of conditionally compiled sections is done using `constexpr if`, where possible.
-Else the C preprocessor (CPP) is used for conditional inclusion (`#if`, ...).
+Else, the C preprocessor (CPP) is used for conditional inclusion (`#if`, ...).
 
 ## Comparison of Options
 
-### Comparing variants Option 1a), b) and c)
+### Comparing variants Option 1a), b), and c)
 
-Assuming that we do define interfaces for one or several HALs, we should not follow the structure of the currently used one just out of convenience (what option 1c) suggests).
-Because that would possibly complicate to write adapters for different HAL implementations.
-And allowing variants is one of the purposes of the adapters.
+Assuming that we do define interfaces for one or several HALs, we should not follow the structure of the currently used one just for convenience (as option 1c suggests).
+This could complicate writing adapters for different HAL implementations.
+Allowing variants is one of the purposes of the adapters.
 
-Instead we should design the interfaces such that they fit the usage.
-In general an object oriented approach is sensible to represent the different peripheral components which are available through HALs.
-Also an object oriented approach is the most straightforward to implement dependency inversion.
+Instead, we should design the interfaces to fit the usage.
+In general, an object-oriented approach is sensible to represent the different peripheral components available through HALs.
+Also, an object-oriented approach is the most straightforward for implementing dependency inversion.
 
-This from those variants, **option 1a)** would be the best.
+From these variants, **option 1a)** would be the best.
 
-### Comparing Options 1a), 2a) and 2b)
+### Comparing Options 1a), 2a), and 2b)
 
 - **Option 1a)**: Implement and use adapters for the complete 3rd party HAL(s)
   - Pros:
-    - Clean separation of concerns, dependency inversion and injection.
-    - Fits to the overall design to use dependency inversion in order to fulfill the 
+    - Clean separation of concerns, dependency inversion, and injection.
+    - Fits the overall design to use dependency inversion to fulfill the
       [dependency rule](<\ref interpretation_dependency_rule> "dependency rule").
-    - Using a different implementation of our - to be defined - HAL interface would not require to modify the users of our HAL interface.
-      Instead only a different adapter - implementing our HAL interface - would be required.[¹](<\ref dr004_1 "¹")
+    - Using a different implementation of our - to be defined - HAL interface would not require modifying the users of our HAL interface.
+      Instead, only a different adapter - implementing our HAL interface - would be required.[¹](<\ref dr004_1 "¹")
   - Cons:
-    - This approach requires to write adapters for all used HAL interfaces to 3rd party libraries.
-      A reusable interface is difficult to design and the adapters may result in boilerplate code.
-      Note, that this approach would mean to write adapters to a HAL implementation, which is an adapter (to proprietary peripheral drivers) in itself.
+    - This approach requires writing adapters for all used HAL interfaces to 3rd party libraries.
+      Designing a reusable interface is challenging, and the adapters may result in boilerplate code.
+      Note that this approach would mean writing adapters to a HAL implementation, which is an adapter (to proprietary peripheral drivers) in itself.
 - **Option 2a)**: Use adapters only for extensions to vanilla ACA
   - Pros:
     - Compared to option 1a), only a fraction of the adapters would need to be written.
   - Cons:
-    - Our board adapters would have a high degree of dependency to the ACA.
-      The *Single Responsibility Principle* is violated[²](<\ref dr004_2 "²") as the board adapters would not only depend on the board and its hardware.
-      But also on an interface of a 3rd party HAL.
-    - To deal with the extensions made compared to vanilla ACA, some adapters need to be written.
-    - Adapting a variation from the ACA in one member function of a class requires to create an interface containing all used member functions of that class.
-      Even if those other member functions are used without alterations.
+    - Our board adapters would have a high degree of dependency on the ACA.
+      The *Single Responsibility Principle* is violated[²](<\ref dr004_2 "²") as the board adapters would not only depend on the board and its hardware but also on an interface of a 3rd party HAL.
+    - Dealing with the extensions made compared to vanilla ACA requires writing some adapters.
+    - Adapting a variation from the ACA in one member function of a class requires creating an interface containing all used member functions of that class, even if those other member functions are used without alterations.
       This introduces *boilerplate code*.
 - **Option 2b)**: Use alternative sections within source files
   - Pros:
     - Reduces the need for additional code to a minimum.
       No adapters need to be written to use the HAL.
   - Cons:
-    - Our board adapters would have a high degree of dependency to the ACA.
-      The *Single Responsibility Principle* is violated[²](<\ref dr004_2 "²") even further (compared to option 2a)) by depending on the vanilla ACA which is required for testing on the native build environment only.
+    - Our board adapters would have a high degree of dependency on the ACA.
+      The *Single Responsibility Principle* is violated[²](<\ref dr004_2 "²") even further (compared to option 2a)) by depending on the vanilla ACA required for testing in the native build environment only.
       Changes to the test infrastructure should not necessitate changes in the source file containing productive code.
-    - In general conditionally compiled sections of code reduces its readability.
+    - In general, conditionally compiled sections of code reduces its readability.
 
 \note \anchor dr004_1
-¹: *In practice* our HAL interface may not be suitable to accommodate the new HAL implementation (see [Rule of Three](https://en.wikipedia.org/w/index.php%3Ftitle%3DRule_of_three_%28computer_programming%29%26oldid%3D1173684754)).
-Thus we would have to adjust our HAL interface and the code using it accordingly.
-In other words: It is difficult to design a HAL interface such that we would actually benefit when changing the HAL implementation to a different 3rd party library. Thus this advantage may not be relevant for that case.  
-Also - in case the HAL implementation is changed - it may be less effort to adjust all the uses of the new HAL interface than to write adapters for the changed 3rd party library.
+¹: *In practice*, our HAL interface may not be suitable to accommodate the new HAL implementation (see [Rule of Three](https://en.wikipedia.org/w/index.php%3Ftitle%3DRule_of_three_%28computer_programming%29%26oldid%3D1173684754)).
+Thus, we would have to adjust our HAL interface and the code using it accordingly.
+In other words, it is difficult to design a HAL interface such that we would actually benefit when changing the HAL implementation to a different 3rd party library.
+Thus, this advantage may not be relevant for that case.  
+Also, in case the HAL implementation is changed, it may be less effort to adjust all the uses of the new HAL interface than to write adapters for the changed 3rd party library.
 
 \note \anchor dr004_2
 ²: The source file (of a non-adapter) would depend on a 3rd party interface.
-Changes to that 3rd party interface may necessitate changes to the source file even though the requirements to that source files remain the same.
+Changes to that 3rd party interface may necessitate changes to the source file even though the requirements to that source file remain the same.
 
 ### Summary & Decision
 
-Writing adapters adds additional effort, potentially boilerplate code and the advantage is dubious.
+Writing adapters adds additional effort, potentially resulting in boilerplate code, and the advantage is dubious.
 
 After careful consideration, we've decided on:
 
-> **Option 2:** Allow direct dependencies from hardware related code to 3rd party HAL interfaces.
+> **Option 2:** Allow direct dependencies from hardware-related code to 3rd party HAL interfaces.
 
 And more specifically for testing on native environments, use:
 
-> **Option 2b):** Where the ACA is used, it is allowed to add small conditionally compiled sections for tests in order to cope with deviations of the ACA used in productive code from the vanilla ACA.
+> **Option 2b):** Where the ACA is used, it is allowed to add small conditionally compiled sections for tests to cope with deviations of the ACA used in productive code from the vanilla ACA.
 
-The latter relaxation is in order to facilitate the use of ArduinoFake to stub the HAL's interface.
+The latter relaxation is to facilitate the use of ArduinoFake to stub the HAL's interface.