More words for initialization FAQ

Author: som-snytt

_overviews/FAQ/initialization-order.md

@@ -7,23 +7,26 @@ permalink: /tutorials/FAQ/:title.html
 
 ## Example
 
-The following example illustrates the problem:
+The following example illustrates how classes in a subclass relation
+witness the initialization of two fields which are inherited from
+their top-most parent. The values are printed during the constructor
+of each class, that is, when an instance is initialized.
 
     abstract class A {
       val x1: String
       val x2: String = "mom"
 
-      println("A: " + x1 + ", " + x2)
+      println(s"A: $x1, $x2")
     }
     class B extends A {
       val x1: String = "hello"
 
-      println("B: " + x1 + ", " + x2)
+      println(s"B: $x1, $x2")
     }
     class C extends B {
       override val x2: String = "dad"
 
-      println("C: " + x1 + ", " + x2)
+      println(s"C: $x1, $x2")
     }
 
 In the Scala REPL we observe:
@@ -33,39 +36,46 @@ In the Scala REPL we observe:
     B: hello, null
     C: hello, dad
 
-Only when we get to the constructor of `C` are both `x1` and `x2` initialized. Therefore, constructors of `A` and `B` risk running into `NullPointerException`s.
+Only when we get to the constructor of `C` are both `x1` and `x2` properly initialized.
+Therefore, constructors of `A` and `B` risk running into `NullPointerException`s,
+since fields are null-valued until set by a constructor.
 
 ## Explanation
 
-A "strict" or "eager" val is one which is not marked lazy.
+A "strict" or "eager" val is a `val` which is not a `lazy val`.
 Initialization of strict vals is done in the following order:
 
 1. Superclasses are fully initialized before subclasses.
-2. Otherwise, in declaration order.
+2. Within the body or "template" of a class, vals are initialized in declaration order,
+   the order in which they are written in source.
 
-When a `val` is overridden, in fact its accessor method (the "getter") is overridden.
-So the access to `x2` in class `A` in fact invokes the overridden getter in class `C` which reads the underlying field `C.x2`.
+When a `val` is overridden, it's more precise to say that its accessor method (the "getter") is overridden.
+So the access to `x2` in class `A` invokes the overridden getter in class `C`.
+That getter reads the underlying field `C.x2`.
 This field is not yet initialized during the construction of `A`.
 
 ## Mitigation
 
-The [`-Ysafe-init` compiler flag](https://docs.scala-lang.org/scala3/reference/other-new-features/safe-initialization.html) in Scala 3 enables compiler warnings for accesses to uninitialized fields:
+The [`-Wsafe-init` compiler flag](https://docs.scala-lang.org/scala3/reference/other-new-features/safe-initialization.html)
+in Scala 3 enables a compile-time warning for accesses to uninitialized fields:
 
-    -- Warning: Test.scala:8:6 ------------------
+    -- Warning: Test.scala:8:6 -----------------------------------------------------
     8 |  val x1: String = "hello"
       |      ^
       |      Access non-initialized value x1. Calling trace:
-      |      ├── class B extends A {	[ Test.scala:7 ]
+      |      ├── class B extends A {        [ Test.scala:7 ]
       |      │   ^
-      |      ├── abstract class A {	[ Test.scala:1 ]
+      |      ├── abstract class A { [ Test.scala:1 ]
       |      │   ^
-      |      └── println("A: " + x1 + ", " + x2)	[ Test.scala:5 ]
-      |                          ^^
+      |      └── println(s"A: $x1, $x2")    [ Test.scala:5 ]
+      |                        ^^
 
 In Scala 2, the `-Xcheckinit` flag adds runtime checks in the generated bytecode to identify accesses of uninitialized fields.
-The code then throws an exception rather than allowing a `null` (or `0` / `false` in the case of primitive types) to silently appear.
-Note that these runtime checks only test code that is actually exectued at runtime.
-The flag can be helpful to find accesses to uninitialized fields, but it should never be used in production due to its performance overhead.
+That code throws an exception when an uninitialized field is referenced
+that would otherwise be used as a `null` value (or `0` or `false` in the case of primitive types).
+Note that these runtime checks only report code that is actually executed at runtime.
+Although these checks can be helpful to find accesses to uninitialized fields during development,
+it is never advisable to enable them in production code due to the performance cost.
 
 ## Solutions
 
@@ -120,25 +130,31 @@ Doing so in Scala 2 can lead to surprising behavior.
 Note that abstract `lazy val`s are supported in Scala 3, but not in Scala 2.
 In Scala 2, you can define an abstract `val` or `def` instead.
 
-An exception during initialization of a lazy val will cause the right-hand side to be re-evaluated on the next access: see SLS 5.2.
+An exception during initialization of a lazy val will cause the right-hand side to be re-evaluated on the next access; see SLS 5.2.
 
-Note that using multiple lazy vals creates a new risk: cycles among lazy vals can result in a stack overflow on first access.
+Note that using multiple lazy vals incurs a new risk: cycles among lazy vals can result in a stack overflow on first access.
+When lazy vals are annotated as thread-safe in Scala 3, they risk deadlock.
 
 ### Use a nested object
 
-Sometimes, uninitialized state in a subclass is accessed during construction of a superclass:
+For purposes of initialization, an object that is not top-level is the same as a lazy val.
+
+There may be reasons to prefer a lazy val, for example to specify the type of an implicit value,
+or an object where it is a companion to a class. Otherwise, the most convenient syntax may be preferred.
+
+As an example, uninitialized state in a subclass may be accessed during construction of a superclass:
 
     class Adder {
       var sum = 0
       def add(x: Int): Unit = sum += x
-      add(1)
+      add(1) // in LogAdder, the `added` set is not initialized yet
     }
     class LogAdder extends Adder {
       private var added: Set[Int] = Set.empty
       override def add(x: Int): Unit = { added += x; super.add(x) }
     }
 
-In this case the state can be initialized on demand by wrapping it into a local object:
+In this case, the state can be initialized on demand by wrapping it in a local object:
 
     class Adder {
       var sum = 0
@@ -155,6 +171,10 @@ In this case the state can be initialized on demand by wrapping it into a local
 
 ### Early definitions: deprecated
 
-Scala 2 supports early definitinos, but they are deprecated in Scala 2.13 and unsupported in Scala 3.
+Scala 2 supports early definitions, but they are deprecated in Scala 2.13 and unsupported in Scala 3.
 See the [migration guide](https://docs.scala-lang.org/scala3/guides/migration/incompat-dropped-features.html#early-initializer) for more information.
 
+Constant value definitions (specified in SLS 4.1 and available in Scala 2)
+and inlined definitions (in Scala 3) can work around initialization order issues
+because they can supply constant values without evaluating an instance that is not yet initialized.
+