Jeremy Caney (28) [Avatar] Offline
#1
Steven, Mark…

Here's my feedback for Chapter 2. There's considerably less of it than for Chapter 1 (which I'm sure is a relief). As a head's up, I should also be able to type of my feedback for Chapter 3 tomorrow.

Typos
Most of these would likely be picked up by you or your copy editors on a future pass, but I figured I'd flag them while I'm at it. These are minor typos that are easy to fix.

  • 2: There is an unnecessary "a" in "…we'll do a complete rewrite of this tightly-coupled code base to a one that is loosely-coupled."

  • 2: In the last paragraph, "focusses" should be spelled "focuses".

  • 2.1.1: In the final bullet list, "that" should be "which" in "…the Razor view, which will eventually render the list of featured products."

  • 2.1.2: In the first annotation, it should read, "…the underlying database's Products table."

  • 2.1.2: The Note at the end of the section should begin with, "The Domain Logic Layer is…"

  • 2.1.3: In the second bullet right after Listing 2.3, "Get's" should be "Get".

  • 2.1.3: Under User Interface Layer, in the Warning right before Listing 2.5, "This wouldn't be that bad when…" should be "This wouldn't be that bad if…", since the ProductService will always be considered a Volatile Dependency.

  • 2.1.3: Under User Interface Layer, in the Warning right before Listing 2.5, "Volatile Dependency" is misspelled as "Volatile Depependency".

  • 2.1.3: Under User Interface Layer, in the Note right before Listing 2.5, it should either be "…an alternative approach that…" or "…an alternative approach, which…'

  • 2.1.3: In the annotations for Listing 2.5, it should read, "Gets the products populated by the Controller."

  • 2.1.3:In the annotations for Listing 2.5, there is an orphaned referenced to an annotation #3 which doesn't exist in the annotations.

  • 2.2.3: Under Figure 2.8, "…both User Interface and Domain libraries…" should be "…both the User Interface and Domain libraries…"

  • 2.4: In the second-to-last bullet, it should be "Mary's application caused us to lose…" not "Mary's application, cause us to loose…"


  • Punctuation and Formatting
    The items in this section aren't necessarily typos—or even incorrect, per se—but are minor changes, primarily to the punctuation and formatting, that might improve the flow by e.g. joining related ideas, separating out concepts, or emphasizing an identifier as code.

  • 2.1.2: The font in the paragraph after Figure 2.3 is too large, at least in my e-reader; it should be the same size as the rest of the body font.

  • 2.1.3: In the first sentence, "Products" should either be "Products" or lowercase.

  • 2.3.1: I'd recommend making the titles of each bullet bold and/or italic so it's easy to quickly skim them. This will help break down the text.

  • 2.3.1: Under the Parallel development bullet, add hyphens: "A well-designed, loosely-[/color=coupled system…"

  • 2.3.1: Under the Parallel development bullet, add commas on either side of "however": "Testing code without a database[color=red], however, is a prerequisite for doing unit testing." (This applies to a number of instances of "however" throughout much of the book.)

  • 2.3.1: After the bullet list, there is an extraneous comma in: "At this point you may ask yourself, what the desired dependency graph should look like."

  • 2.3.3: I'd generally avoid having multiple paragraphs within a single bulleted item, as it makes for awkward formatting. In the second bullet point, it's also not necessary.


  • Readability Suggestions
    The following are areas I found myself tripping over the wording, possibly due to repetition of words, run-on sentences, or simply words that, while correct, interfered with the readability of the content. These are fairly subjective, and more subject to stylistic preferences, so take them with a grain of salt. At the same time, these are also the trickiest issues for me to pick up when proof-reading my own writing, so I figured I'd document them.

  • 2: To clarify what you are composing, consider adding e.g., "…but ultimately we must still compose this complex set of concerns into a cohesive application."

  • 2.1.2: In Listing 2.2, to avoid the wordy "…because we less have to deal with querying the database", consider replacing with "…instead of querying the database directly"

  • 2.1.2: In the Entity Framework crash course, "In Entity Framework, DbContext…" is largely implicit, and can be replaced with simply: "This allows access to data in the database…"

  • 2.2: In the last sentence, consider, "Every time we add a reference, though, we take on a Dependency" to emphasize that this is a counterpoint to the previous point regarding how easy it is to add references.

  • 2.2.1: In the first paragraph of Evaluating Composability, it should be "…each area of the application in isolation" not "…one area of the application in isolation".

  • 2.2.1: In the Note right before the end, it should read "…but be aware that this is just a technique we use…" to emphasize that this has a limited purpose.

  • 2.2.4: Add, "For instance, we could ask whether…" to emphasize that this is an illustration of the previous sentence.

  • 2.2.4: Add, "But in most cases, this would be an odd question…" to emphasize that this is contrary to the previous point.

  • 2.3.1: To remove the repetition of "benefits" consider introducing the bullet list with "…we see that Mary's application fails to have the following:"

  • 2.3.1: Under the Maintainability bullet, add "…but every newly-added…" to indicate that this is the contrast to the opening "Not only…"

  • 2.3.1: Under the Maintainability bullet, changed "…make each touched class even more complex." to "…make each class touched even more complex."

  • 2.3.1: Under the Parallel development bullet, change "Just like us, you likely dealt with…" to "Just like us, you have likely dealt with…"

  • 2.3.1: Under the Testability bullet, "…but the current design…" to "…and the current design…" to avoid the wordy "But… but…"

  • 2.3.1: Under the Testability bullet, change "therefore is" to "is therefore" to ease the flow: "Mary's application is therefore not testable."

  • 2.3.1: In the second paragraph after the bullet list, end with "…other layers can safely depend on it" to avoid the repetition of "Domain Layer".

  • 2.3.3: In the third bullet, the sentence starting with "But even if she would have…" is a bit awkward. It may help if the comma after "…from the perspective of its consumers…" was removed. It would also help if you could remove the repetition of "from" somehow, which makes it wordier. Otherwise, move the interjection to the end, "…the dependency on this configuration value is still very implicit from the perspective of the consumer."

  • 2.3.3: I know what you mean by "In the end, the ultimate caller is the application itself", but this can be a bit ambiguous and, therefore, confusing since we might think of the entire solution as the application. Consider ways of disambiguating that.

  • 2.4: "Visual Studio makes it easy to add it" is a bit wordy; consider simply "Visual Studio makes it easy to add"; the final "it" isn't necessary here.

  • 2.4: To reduce the repetition of "tight coupling" I'd recommend, "…not all tight coupling is bad, but we should strive to prevent it with Volatile Dependencies."

  • 2.4: In the final paragraph, "…we yet have to show you…" would read better as "…we have yet to show you…"

  • 2.4: In the last bullet, add "…from a configuration file directly since the issue isn't that they're being configured, but that they're aware of the configuration file.

  • 2.4: In the last bullet, "instead should" would read better as "…but should instead be configurable by their callers."


  • Content Suggestions
    The following are more invasive changes related to organization and order of content, technical details, &c.

  • 2: In introducing the tightly-coupled code (e.g., around "You'll see how easy it is to write…"), it would be valuable to emphasize that e.g., "every effort was made to ensure this is a realistic example of an approach you may see in a real-world application; i.e., this is not meant to be a straw man."

  • 2: The last paragraph is largely redundant with the second-to-last paragraph. Since the opening section is so short, it doesn't necessitate a closing summary. Given this, consider merging it with the previous paragraph—or even removing it entirely.

  • 2.1.2: In the Entity Framework crash course callout, consider clarifying "Entity Framework will do the querying for us, via e.g. LINQ expressions." This is less ambiguous than "transformations" for developers that haven't worked with Entity Framework.

  • 2.1.3: In the paragraph after Listing 2.3, "passing in the isCustomerPreferred parameter" might make more sense as "accepting an isCustomerPreferred parameter" since you're currently speaking from the perspective of the Domain Layer.

  • 2.1.3: Because the three-tier architecture is so ubiquitous, and the content of each section isn't very long, I'm not certain the progress reports (i.e., Figure 2.3, Figure 2.4, and Figure 2.5) or their accompanying text (e.g., "Figure 2.4 shows how far Mary has come…") adds that much value, and especially relative to how much space they take up. Consider removing.

  • 2.2: The question "or did she?" is largely redundant with the subsequent, "Did Mary succeed…?"; the two can probably be merged with, "But did Mary actually succeed…?" This might also have more impact.

  • 2.3.1: In the Extensibility bullet, consider adding, "Doing so will require many classes in the system to be changed; it would also require implementors to have access to the source code, which may not be the case." The helps address the benefits of extensibility in terms of libraries, products, and other forms of reusable code.

  • 2.3.1: As a total nit-pick, technically "The next figure is a big spoiler" not a "spoiler alert"; that sentence is a spoiler alert about the figure, but the figure itself is just a spoiler.


  • General Feedback
    There's no action necessary on the following; they're just comments that popped up as I was going through the book.

  • 2: Overall, I found this chapter really well organized and easy to digest. I also found it humbling (if not shameful) as I've written plenty of applications with similar mistakes in the past—which also reinforces precisely why this is such a useful exercise. I suspect most of your readers are in the same boat—and if they're initially wondering, "what's so bad about this approach?" then they're most certainly reading the right book!

  • 2.2.4: I appreciated this section as this was something I kept tripping over when I first tried implementing Dependency Injection in an app; between this and the Composition Root, I felt like a) I kept just "kicking the can down the road", and b) establishing exercises in formality which added complexity without obvious benefits. This section, along with the previous distinction of Volatile Dependencies, really helps isolate where to introduce seams and abstractions.

  • 2.3.3: This may well be a matter of debate, but in the last bullet point, I'd consider string formatting, in general, to be well within the potential functionality of a View. I suppose the argument is that it's not especially friendly for e.g. designers that might be working on the view? (Obviously, avoiding the cast is certainly preferable, if possible.)

  • Do let me know if there's anything I can do to make this feedback easier to review (e.g., provide more or less context, mark changes different, &c.).

    Jeremy
    Steven van Deursen (32) [Avatar] Offline
    #2
    Hi Jemery,

    Again many thanks for providing this feedback. Your feedback is very welcome and again useful. I already processed your comments and updated the text accordingly.

    Cheers

    Steven
    Francois Genolini (2) [Avatar] Offline
    #3
    Hi, thanks again for the early availability of your book.

    Section 2.1.2, p. 40, "Entity Framework crash course" insert
    the phrasing <<we less have to deal>> does not read well for me, perhaps <<we have to deal less>> would work better?

    Section 2.5, p. 55, spelling mistake
    <<cause us to loose the benefits that loose>>, should be <<cause us to lose the benefits that loose>>
    also lose / loose are a form of repetition, maybe use <<forfeit>> instead of <<lose>>