add suggestions, thoughts

Author: Xronophobe

chapter_27_hot_lava.asciidoc

@@ -271,11 +271,23 @@ Functional/End-to-end tests::
     including all dependencies and connected external systems.
     They are the ultimate test that it all hangs together,
     and that things are "really" going to work.
-
+    // CSANAD: I find the expression 'things are "really" going to work' too vague.
+    // I would rather mention User Stories here, since they very often can be turned into
+    // functional/end-to-end tests: they are worded similarly and they both cover specific
+    // functionalities that are valuable for a given user (edit: well, you talk
+    // about this below, under "On Acceptance Tests").
+    // Furthermore, I would maybe give an example for each:
+    // "Francis starts a new list by entering a new item."
 
 Integration tests::
     The purpose of integration tests should be to check that the code
     you write is integrated correctly with some "external" system or dependency.
+    // CSANAD: this one is more tricky to find integration tests for, since we
+    // didn't create separate 'integration tests'. Maybe an example could be
+    // checking whether Bootstrap is loaded correctly, or perhaps the email.
+    // Something like that would be helpful in my opinion, especially because
+    // we promised in Chapter 05 ("Unit Tests Versus Integration Tests, and the Database")
+    // that we would further clarify the difference.
 
 
 (True) Unit tests::
@@ -284,6 +296,10 @@ Integration tests::
     The ideal unit test is fully isolated
     from everything external to the unit under test
     such that changes to things outside cannot break the test.
+    // CSANAD: I was trying to find an example of a pure unit test. I recall
+    // we may have had some helper function at some point, for which there was
+    // no need to use Django's TestCase but I can't find it. Maybe I'm
+    // remembering wrong.
 
 The canonical advice is that you should aim to have the majority of your tests
 be unit tests, with a smaller number of integration tests,
@@ -313,6 +329,10 @@ Top Layer: A minimal set of Functional/End-to-End Tests::
     But because they are the slowest and most brittle,
     we want as few of them as possible.
 
+// CSANAD: I think explaining the layers after having explained the types of
+// tests just above it, seems a little redundant. I wonder if we should combine
+// them.
+
 
 [[acceptance-tests-sidebar]]
 .On Acceptance Tests
@@ -363,6 +383,8 @@ Ed Jung calls this https://youtu.be/CdKaZ7boiZ4[Mock Hell].
 This isn't to say that mocks are always bad!
 But just that, from experience,
 attempting to use them as your primary tool for decoupling
+// CSANAD: I think we could actually argue that by using mocks, we
+// accept that the code is tightly coupled with its dependencies.
 your tests from external dependencies is not a viable solution;
 it carries costs that often outweigh the benefits.
 
@@ -376,7 +398,7 @@ NOTE: I'm glossing over the use of mocks in a "London-school"
 The actual solution to the problem isn't obvious from where we're standing,
 but it lies in rethinking the architecture of our application.
 In brief, if we can _decouple_ the core business logic of our application
-from its dependencies, then we can write true unit tests for it,
+from its dependencies, then we can write true, isolated unit tests for it,
 that do not depend on those, um, dependencies.
 
 Integration tests are most necessary at the _boundaries_ of a system--at
@@ -433,6 +455,12 @@ call this approach "Ports and Adapters" (see <<ports-and-adapters>>).
 .Ports and Adapters (diagram by Nat Pryce)
 image::images/twp2_2601.png["Illustration of ports and adapaters architecture, with isolated core and integration points"]
 
+// CSANAD: I haven't found the original diagram by Nat Pryce. I would recommend
+// maybe a making the next header "Functional Core, Imperative Shell" formatted
+// differently, making it more obvious that it's an explanation of the diagram.
+// Or, we could just add a "Legend" under the diagram, explaining what the
+// nodes, arrows and different shades of the layers depict.
+
 This pattern, or variations on it, are known as
 "Hexagonal Architecture" (by Alistair Cockburn),
 "Clean Architecture" (by Robert C. Martin, aka Uncle Bob),
@@ -508,6 +536,7 @@ aren't the be-all and end-all.
 image::images/frog-in-a-pan-placeholder.png["An illustration of a frog being slowly boiled in a pan"]
 
 * TODO: update image
+// CSANAD: I like this placeholder :D
 
 For small to medium-sized applications, as we've seen, the Django test runner
 and the integration tests it encourages us to write are just fine.