ploeh blog 2020-07-10T05:33:08+00:00 Mark Seemann danish software design https://blog.ploeh.dk Referential transparency of IO https://blog.ploeh.dk/2020/07/06/referential-transparency-of-io 2020-07-06T05:56:00+00:00 Mark Seemann <div id="post"> <p> <em>How the IO container guarantees referential integrity. An article for object-oriented programmers.</em> </p> <p> This article is part of <a href="/2020/06/08/the-io-container">an article series about the IO container in C#</a>. In <a href="/2020/06/15/io-container-in-a-parallel-c-universe">a previous article</a> you got a basic introduction to the <code>IO&lt;T&gt;</code> <a href="https://bartoszmilewski.com/2014/01/14/functors-are-containers">container</a> I use to explain how a type system like <a href="https://www.haskell.org">Haskell</a>'s distinguishes between <a href="https://en.wikipedia.org/wiki/Pure_function">pure functions</a> and impure actions. </p> <p> The whole point of the <code>IO</code> container is to effectuate the <a href="/2018/11/19/functional-architecture-a-definition">functional interaction law</a>: <em>a pure function mustn't be able to invoke an impure activity.</em> This rule follows from <a href="https://en.wikipedia.org/wiki/Referential_transparency">referential transparency</a>. </p> <p> The practical way to think about it is to consider the two rules of pure functions: <ul> <li>Pure functions must be deterministic</li> <li>Pure functions may have no side effects</li> </ul> In this article, you'll see how <code>IO&lt;T&gt;</code> imposes those rules. </p> <h3 id="3b648ec5b32a42e4b608dbc2e8861a86"> Determinism <a href="#3b648ec5b32a42e4b608dbc2e8861a86" title="permalink">#</a> </h3> <p> Like in the previous articles in this series, you must imagine that you're living in a parallel universe where all impure library functions return <code>IO&lt;T&gt;</code> objects. By elimination, then, methods that return naked values must be pure functions. </p> <p> Consider the <code>Greet</code> function from the <a href="/2020/06/15/io-container-in-a-parallel-c-universe">previous article</a>. Since it returns a plain <code>string</code>, you can infer that it must be a pure function. What prevents it from doing something impure? </p> <p> What if you thought that passing <code>now</code> as an argument is a silly design. Couldn't you just call <code>Clock.GetLocalTime</code> from the method? </p> <p> Well, yes, in fact you can: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;Greet(<span style="color:#2b91af;">DateTime</span>&nbsp;now,&nbsp;<span style="color:blue;">string</span>&nbsp;name) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">DateTime</span>&gt;&nbsp;now1&nbsp;=&nbsp;<span style="color:#2b91af;">Clock</span>.GetLocalTime(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Hello&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsMorning(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;morning&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsAfternoon(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;afternoon&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsEvening(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;evening&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(<span style="color:blue;">string</span>.IsNullOrWhiteSpace(name)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#a31515;">$&quot;</span>{greeting}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#a31515;">$&quot;</span>{greeting}<span style="color:#a31515;">,&nbsp;</span>{name.Trim()}<span style="color:#a31515;">.&quot;</span>; }</pre> </p> <p> This compiles, but is only the first refactoring step you have in mind. Next, you want to extract the <code>DateTime</code> from <code>now1</code> so that you can get rid of the <code>now</code> parameter. Alas, you now run into an insuperable barrier. <a href="/2019/02/04/how-to-get-the-value-out-of-the-monad">How do you get the DateTime out of the IO?</a> </p> <p> You can't. By design. </p> <p> While you can call the <code>GetLocalTime</code> method, you can't <em>use</em> the return value. The only way you can use it is by composing it with <code>SelectMany</code>, but that still accomplishes nothing unless you return the resulting <code>IO</code> object. If you do that, though, you've now turned the entire <code>Greet</code> method into an impure action. </p> <p> You can't perform any non-deterministic behaviour inside a pure function. </p> <h3 id="9f62e432e0c74fda93aff427774c0183"> Side effects <a href="#9f62e432e0c74fda93aff427774c0183" title="permalink">#</a> </h3> <p> How does <code>IO&lt;T&gt;</code> protect against side effects? In the <code>Greet</code> method, couldn't you just write to the console, like the following? </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;Greet(<span style="color:#2b91af;">DateTime</span>&nbsp;now,&nbsp;<span style="color:blue;">string</span>&nbsp;name) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Console</span>.WriteLine(<span style="color:#a31515;">&quot;Side&nbsp;effect!&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Hello&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsMorning(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;morning&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsAfternoon(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;afternoon&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsEvening(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;evening&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(<span style="color:blue;">string</span>.IsNullOrWhiteSpace(name)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#a31515;">$&quot;</span>{greeting}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#a31515;">$&quot;</span>{greeting}<span style="color:#a31515;">,&nbsp;</span>{name.Trim()}<span style="color:#a31515;">.&quot;</span>; }</pre> </p> <p> This also compiles, despite our best efforts. That's unfortunate, but, as you'll see in a moment, it doesn't violate referential transparency. </p> <p> In Haskell or <a href="https://fsharp.org">F#</a> equivalent code would make the compiler complain. Those compilers don't have special knowledge about <code>IO</code>, but they can see that an action returns a value. F# generates a compiler warning if you ignore a return value. In Haskell the story is a bit different, but the result is the same. Those compilers complain because you try to ignore the return value. </p> <p> You can get around the issue using the language's wildcard pattern. This tells the compiler that you're actively ignoring the result of the action. You can do the same in C#: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;Greet(<span style="color:#2b91af;">DateTime</span>&nbsp;now,&nbsp;<span style="color:blue;">string</span>&nbsp;name) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">Unit</span>&gt;&nbsp;_&nbsp;=&nbsp;<span style="color:#2b91af;">Console</span>.WriteLine(<span style="color:#a31515;">&quot;Side&nbsp;effect!&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Hello&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsMorning(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;morning&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsAfternoon(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;afternoon&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsEvening(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;evening&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(<span style="color:blue;">string</span>.IsNullOrWhiteSpace(name)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#a31515;">$&quot;</span>{greeting}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#a31515;">$&quot;</span>{greeting}<span style="color:#a31515;">,&nbsp;</span>{name.Trim()}<span style="color:#a31515;">.&quot;</span>; }</pre> </p> <p> The situation is now similar to the above treatment of non-determinism. While there's no value of interest in an <code>IO&lt;Unit&gt;</code>, the fact that there's an object at all is a hint. Like <code>Lazy&lt;T&gt;</code>, that value isn't a result. It's a placeholder for a computation. </p> <p> If there's a way to make the C# compiler complain about ignored return values, I'm not aware of it, so I don't know if we can get closer to how Haskell works than this. Regardless, keep in mind that I'm not trying to encourage you to write C# like this; I'm only trying to explain how Haskell enforces referential transparency at the type level. </p> <h3 id="4f40c1e1a7a142b693d050dcab466d90"> Referential transparency <a href="#4f40c1e1a7a142b693d050dcab466d90" title="permalink">#</a> </h3> <p> While the above examples compile without warnings in C#, both are still referentially transparent! </p> <p> This may surprise you. Particularly the second example that includes <code>Console.WriteLine</code> looks like it has a side effect, and thus violates referential transparency. </p> <p> Keep in mind, though, what referential transparency means. It means that you can replace a particular function call with its value. For example, you should be able to replace the function call <code>Greeter.Greet(new DateTime(2020, 6, 4, 12, 10, 0), "Nearth")</code> with its return value <code>"Hello, Nearth."</code>, or the function call <code>Greeter.Greet(new DateTime(2020, 6, 4, 7, 30, 0), "Bru")</code> with <code>"Good morning, Bru."</code>, without changing the behaviour of the software. This property still holds. </p> <p> Even when the <code>Greet</code> method includes the <code>Console.WriteLine</code> call, that side effect never happens. </p> <p> The reason is that an <code>IO</code> object represents a potential computation that may take place (also known as a <em>thunk</em>). Notice that the <code>IO&lt;T&gt;</code> constructor takes a <code>Lazy</code> value as argument. It's basically just a <code>Lazy</code> container wrapped in such a way that you can't force evaluation. </p> <p> Instead, you should imagine that <em>after</em> <code>Main</code> returns its <code>IO&lt;Unit&gt;</code> object, the parallel-universe .NET framework executes it. </p> <p> <img src="/content/binary/parallel-universe-fx-calling-unsafeperformio.png" alt="Diagram showing that the parrallel-universe framework executes the IO value after Main returns."> </p> <p> The framework supplies command-line arguments to the <code>Main</code> method. Once the method returns an <code>IO&lt;Unit&gt;</code> object, the framework executes it with a special method that only the framework can invoke. Any other <code>IO</code> values that may have been created (e.g. the above <code>Console.WriteLine</code>) never gets executed, because they're not included in the return value. </p> <h3 id="d5fe0e97d9ea4442b3b4fb13ad28aab6"> Conclusion <a href="#d5fe0e97d9ea4442b3b4fb13ad28aab6" title="permalink">#</a> </h3> <p> The <code>IO</code> container makes sure that pure functions maintain referential transparency. The underlying assumption that makes all of this work is that <em>all</em> impure actions return <code>IO</code> objects. That's not how the .NET framework works, but that's how Haskell works. Since the <code>IO</code> container is opaque, pure functions can't see the contents of <code>IO</code> boxes. </p> <p> Program <a href="https://en.wikipedia.org/wiki/Entry_point">entry points</a> are all impure. The return value of the entry point must be <code>IO&lt;Unit&gt;</code>. The hypothetical parallel-universe framework executes the <code>IO</code> value returned by <code>Main</code>. </p> <p> Haskell is a lazily evaluated language. That's an important piece of the puzzle, so I've modelled the <code>IO&lt;T&gt;</code> example so that it only wraps <code>Lazy</code> values. That emulates Haskell's behaviour in C#. In the next article, you'll see how I wrote the C# code that supports these articles. </p> <p> <strong>Next:</strong> Implementation of the C# IO container. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="52e8a987dc234e839d259cc3296176d7"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> In a <a href="https://blog.ploeh.dk/2020/02/24/discerning-and-maintaining-purity/">previous post</a>, you said </p> <blockquote> ...a <a href="https://en.wikipedia.org/wiki/Pure_function">pure function</a> has to obey two rules: <ul> <li>The same input always produces the same output.</li> <li>Calling it causes no side effects.</li> </ul> </blockquote> <p> In this post, you said </p> <blockquote>...the two rules of pure functions: <ul> <li>Pure functions must be deterministic</li> <li>Pure functions may have no side effects</li> </ul> </blockquote> <p> The first two items are not the same. Is this difference intentional? </p> </div> <div class="comment-date">2020-07-06 11:07 UTC</div> </div> <div class="comment" id="73bfc62f4f464ac2b5a6131e95884c11"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for writing. Indeed, the words er verbatim not the same, but I do intend them to carry the same meaning. </p> <p> If one wants to define purity in a way that leaves little ambiguity, one has to use more words. Just look at the linked Wikipedia article. I link to Wikipedia for the benefit of those readers who'd like to get a more rigorous definition of the term, while at the same time I enumerate the two rules as a summary for the benefit of those readers who just need a reminder. </p> <p> Does that answer your question? </p> </div> <div class="comment-date">2020-07-06 11:26 UTC</div> </div> <div class="comment" id="1338dd35c4c6405f861ffa26034b13e6"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> ...I do intend them to carry the same meaning. </blockquote> <p> I don't think they don't mean the same thing. That is part of the discussion we are having on <a href="https://blog.ploeh.dk/2020/02/24/discerning-and-maintaining-purity/">this previous post</a>. I think the simplest example to see the difference is randomzied quicksort. For each input, the output is always the same. However, randomized quicksort is not deterministic because it uses randomness. </p> <p> Do you still think they mean the same thing? </p> </div> <div class="comment-date">2020-07-06 19:35 UTC</div> </div> <div class="comment" id="247a2c05d83a485a99225057829afa71"> <div class="comment-author"><a href="http://www.raboof.com/">Atif Aziz</a></div> <div class="comment-content"> <blockquote> You can get around the issue using the language's wildcard pattern. This tells the compiler that you're actively ignoring the result of the action. </blockquote> <p> You made a standard variable declaration and I believe you meant to use a <a href="https://docs.microsoft.com/en-us/dotnet/csharp/discards#a-standalone-discard">stand-alone discard</a> rather than a wildcard pattern? Like below? </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;Greet(<span style="color:#2b91af;">DateTime</span>&nbsp;now,&nbsp;<span style="color:blue;">string</span>&nbsp;name) { &nbsp;&nbsp;&nbsp;&nbsp;_&nbsp;=&nbsp;<span style="color:#2b91af;">Console</span>.WriteLine(<span style="color:#a31515;">&quot;Side&nbsp;effect!&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Hello&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsMorning(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;morning&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsAfternoon(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;afternoon&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsEvening(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;evening&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(<span style="color:blue;">string</span>.IsNullOrWhiteSpace(name)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#a31515;">$&quot;</span>{greeting}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#a31515;">$&quot;</span>{greeting}<span style="color:#a31515;">,&nbsp;</span>{name.Trim()}<span style="color:#a31515;">.&quot;</span>; }</pre> </p> </div> <div class="comment-date">2020-07-09 08:18 UTC</div> </div> <div class="comment" id="dcd18dda3cf742ffb0bba38ce0326b66"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, I apologise in advance for my use of <a href="https://en.wikipedia.org/wiki/Weasel_word">weasel words</a>, but 'in the literature', a function that always returns the same output when given the same input is called 'deterministic'. I can't give you a comprehensive list of 'the literature' right now, but <a href="https://en.wikipedia.org/wiki/Deterministic_algorithm">here's at least one example</a>. </p> <p> I'm well aware that this might be confusing. One could argue that querying a database is deterministic, because the output is completely determined by the state of the database. The same goes for reading the contents of a file. Such operations, however, may return different outputs for the same inputs, as the state of the resource changes. There's no stochastic process involved in such state changes, but we still consider such actions non-deterministic. </p> <p> In the same vein, in this jargon, 'deterministic' doesn't imply the absence of internal randomness, as <a href="/2020/02/24/discerning-and-maintaining-purity#a06da27b57944c89aefc16914234939c">you have so convincingly argued</a>. In the present context, 'deterministic' is <em>defined</em> as the property that a given input value always produces the same output value. </p> <p> That's the reason I tend to use those phrases interchangeably. In this context, they literally mean the same. I can see how this might be confusing, though. </p> </div> <div class="comment-date">2020-07-09 10:57 UTC</div> </div> <div class="comment" id="d0dc32b4548a4d4ab5d55652a7b42502"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Atif, thank you for writing. I didn't know about that language construct. Thank you for pointing it out to me! </p> </div> <div class="comment-date">2020-07-09 18:11 UTC</div> </div> <div class="comment" id="956af671404548038caa603fede12e88"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> <p> [<a href="https://en.wikipedia.org/wiki/Deterministic_algorithm">Wikipedia</a> says that] a function that always returns the same output when given the same input is called 'deterministic'. </p> <p> In the same vein, in this jargon, 'deterministic' doesn't imply the absence of internal randomness, as <a href="/2020/02/24/discerning-and-maintaining-purity#a06da27b57944c89aefc16914234939c">you have so convincingly argued</a>. In the present context, 'deterministic' is <em>defined</em> as the property that a given input value always produces the same output value. </p> <p> That's the reason I tend to use those phrases interchangeably. In this context, they literally mean the same. I can see how this might be confusing, though. </p> </blockquote> <p> I am certainly still confused.  I can't tell if you are purposefully providing your own definition for determinism, if you are accidentally misunderstanding the actual definition of determinism, if you think the definition of determinism is equivalent to the definition you gave due to being in some context or operating with an additional assumption (of which I am unsure), or maybe something else. </p> <p> If I had to guess, then I think you do see the difference between the two definitions but are claiming that are equivalent due to being in some context or operating with an additional assumption.  If this guess is correct, then what is the additional assumption you are making? </p> <p> To ensure that you do understand determinism, I will interpret your statements as literally as possible and then respond to them.  I apologize in advance if this is not the correct interpretation and for any harshness in the tone of my response. </p> <p> You misquoted the Wikipedia article.  Here is the exact text (after replacing "algorithm" with "function" since the difference between these is not important to us now). </p> <blockquote> a deterministic function is a function which, given a particular input, will always produce the same output, with the underlying machine always passing through the same sequence of states. </blockquote> <p> Your quotation essentially excludes the phrase "with the underlying machine always passing through the same sequence of states".  Let's put these two definitions next to each other. </p> <p> Let <code>f</code> be a function.  Consider the following two statements about <code>f</code> that might or might not be true (depending on the exact value of <code>f</code>). <ol> <li>Given a particular input, <code>f</code> will always produce the same output.</li> <li>Given a particular input, <code>f</code> will always produce the same output, with the underlying machine always passing through the same sequence of states.</li> </ol> </p> <p> Suppose some <code>f</code> satisfies statement 2.  Then <code>f</code> clearly satisfies statement 1 as well.  These two sentences together are equivalent to saying that statement 2 implies statement 1.  The <a href="https://en.wikipedia.org/wiki/Contraposition">contrapositive</a> then says that not satisfying statement 1 implies not satisfying statement 2.   Also, Wikipedia says that such an <code>f</code> is said to be deterministic. </p> <p> Now suppose some <code>f</code> satisfies statement 1.  Then <code>f</code> need not also satisfy statement 2.  An example that proves this is randomized quicksort (as I pointed out in <a href="https://blog.ploeh.dk/2020/02/24/discerning-and-maintaining-purity/#a06da27b57944c89aefc16914234939c">this comment</a>).  This means that statement 1 does not imply statement 2. </p> <p> "Wikipedia gave" a name to functions that satisfy statement 2.  I do not recall ever seeing anyone give a name to functions that satisfy statement 1.  In <a href="https://blog.ploeh.dk/2020/02/24/discerning-and-maintaining-purity/#9f9664e29c3f4fafa786abae039eb20e">this comment</a>, you asked me about what I meant by "weak determinism".  I am trying to give a name to functions that satisfy statement 1.  I am suggesting that we call them weakly deterministic.  This name allows us to say that a deterministic function is also weakly deterministic, but a weakly deterministic function might not be deterministic.  Furthermore, not being a weakly deterministic implies not being deterministic. </p> <blockquote> One could argue that querying a database is deterministic, because the output is completely determined by the state of the database. The same goes for reading the contents of a file. Such operations, however, may return different outputs for the same inputs, as the state of the resource changes. There's no stochastic process involved in such state changes, but we still consider such actions non-deterministic. </blockquote> <p> Indeed.  I agree.  If we distinguish determinism from weak determinism, then we can say that such a function is not weakly deterministic, which implies that it is not deterministic. </p> </div> <div class="comment-date">2020-07-10 01:36 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Syntactic sugar for IO https://blog.ploeh.dk/2020/06/29/syntactic-sugar-for-io 2020-06-29T05:49:00+00:00 Mark Seemann <div id="post"> <p> <em>How to make use of the C# IO container less ugly.</em> </p> <p> This article is part of <a href="/2020/06/08/the-io-container">an article series about the IO container in C#</a>. In <a href="/2020/06/15/io-container-in-a-parallel-c-universe">the previous article</a> you saw a basic C# <a href="https://en.wikipedia.org/wiki/%22Hello,_World!%22_program">hello world</a> program using <code>IO&lt;T&gt;</code> to explicitly distinguish between <a href="https://en.wikipedia.org/wiki/Pure_function">pure functions</a> and impure actions. The code wasn't as pretty as you could hope for. In this article, you'll see how to improve the aesthetics a bit. </p> <p> The code isn't going to be perfect, but I think it'll be better. </p> <h3 id="c919d892a9374cd4a816693c62840620"> Sugared version <a href="#c919d892a9374cd4a816693c62840620" title="permalink">#</a> </h3> <p> The <code>IO&lt;T&gt;</code> container is an imitation of the <a href="https://www.haskell.org">Haskell</a> <code>IO</code> type. In Haskell, <code>IO</code> is a monad. This isn't a monad tutorial, and I hope that you're able to read the article without a deep understanding of monads. I only mention this because when you compose monadic values with each other, you'll sometimes have to write some 'noisy' code - even in Haskell. To alleviate that pain, Haskell offers syntactic sugar in the form of so-called <code>do</code> notation. </p> <p> Likewise, <a href="https://fsharp.org">F#</a> comes with <a href="https://docs.microsoft.com/dotnet/fsharp/language-reference/computation-expressions">computation expressions</a>, which also gives you syntactic sugar over monads. </p> <p> C#, too, comes with syntactic sugar over monads. This is <em>query syntax</em>, but it's not as powerful as Haskell <code>do</code> notation or F# computation expressions. It's powerful enough, though, to enable you to improve the <code>Main</code> method from the previous article: </p> <p> <pre><span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">Unit</span>&gt;&nbsp;Main(<span style="color:blue;">string</span>[]&nbsp;args) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">from</span>&nbsp;&nbsp;&nbsp;&nbsp;_&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Console</span>.WriteLine(<span style="color:#a31515;">&quot;What&#39;s&nbsp;your&nbsp;name?&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">from</span>&nbsp;name&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Console</span>.ReadLine() &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">from</span>&nbsp;&nbsp;now&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Clock</span>.GetLocalTime() &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;greeting&nbsp;=&nbsp;<span style="color:#2b91af;">Greeter</span>.Greet(now,&nbsp;name) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">from</span>&nbsp;&nbsp;res&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:#2b91af;">Console</span>.WriteLine(greeting) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">select</span>&nbsp;res; }</pre> </p> <p> If you use C# query syntax at all, you may think of it as exclusively the realm of object-relational mapping, but in fact it works for any monad. There's no data access going on here - just the interleaving of pure and impure code (in an <a href="/2020/03/02/impureim-sandwich">impureim sandwich</a>, even). </p> <h3 id="326b00adfdd347e684f5adfc90b001e6"> Infrastructure <a href="#326b00adfdd347e684f5adfc90b001e6" title="permalink">#</a> </h3> <p> For the above code to compile, you must add a pair of methods to the <code>IO&lt;T&gt;</code> API. You can write them as extension methods if you like, but here I've written them as instance methods on <code>IO&lt;T&gt;</code>. </p> <p> When you have multiple <code>from</code> keywords in the same query expression, you must supply a particular overload of <code>SelectMany</code>. This is an oddity of the implementation of the query syntax language feature in C#. You don't have to do anything similar to that in F# or Haskell. </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">TResult</span>&gt;&nbsp;SelectMany&lt;<span style="color:#2b91af;">U</span>,&nbsp;<span style="color:#2b91af;">TResult</span>&gt;( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">T</span>,&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">U</span>&gt;&gt;&nbsp;k, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">T</span>,&nbsp;<span style="color:#2b91af;">U</span>,&nbsp;<span style="color:#2b91af;">TResult</span>&gt;&nbsp;s) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;SelectMany(x&nbsp;=&gt;&nbsp;k(x) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.SelectMany(y&nbsp;=&gt;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">TResult</span>&gt;(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Lazy</span>&lt;<span style="color:#2b91af;">TResult</span>&gt;(s(x,&nbsp;y))))); }</pre> </p> <p> Once you've implemented such overloads a couple of times, they're more tedious than challenging to write. They always follow the same template. First use <code>SelectMany</code> with <code>k</code>, and then <code>SelectMany</code> again with <code>s</code>. The only marginally stimulating part of the implementation is figuring out how to wrap the return value from <code>s</code>. </p> <p> You're also going to need <code>Select</code> as shown in the article about <a href="/2020/06/22/the-io-functor">IO as a functor</a>. </p> <h3 id="589ab47b68244e21bafd2f16c4422800"> Conclusion <a href="#589ab47b68244e21bafd2f16c4422800" title="permalink">#</a> </h3> <p> C#'s query syntax offers limited syntactic sugar over <a href="/2018/03/22/functors">functors</a> and monads. Compared with F# and Haskell, the syntax is odd and its functionality limited. The most galling lacuna is that you can't branch (e.g. use <code>if</code> or <code>switch</code>) inside query expressions. </p> <p> The point of these articles is (still) not to endorse this style of programming. While the code I show in this article series is working C# code that runs and passes its tests, I'm pretending that all impure actions in C# return <code>IO</code> results. To be clear, the <code>Console</code> class this code interacts with isn't <a href="https://docs.microsoft.com/dotnet/api/system.console">the Console class from the base class library</a>. It's a class that pretends to be such a class from a parallel universe. </p> <p> So far in these articles, you've seen how to compose impure actions with pure functions. What I haven't covered yet is the motivation for it all. We want the compiler to enforce the <a href="/2018/11/19/functional-architecture-a-definition">functional interaction law</a>: a pure function shouldn't be able to invoke an impure action. That's the topic for the next article. </p> <p> <strong>Next:</strong> <a href="/2020/07/06/referential-transparency-of-io">Referential transparency of IO</a>. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. The IO functor https://blog.ploeh.dk/2020/06/22/the-io-functor 2020-06-22T06:23:00+00:00 Mark Seemann <div id="post"> <p> <em>The IO container forms a functor. An article for object-oriented programmers.</em> </p> <p> This article is an instalment in <a href="/2018/03/22/functors">an article series about functors</a>. Previous articles have covered <a href="/2018/03/26/the-maybe-functor">Maybe</a>, <a href="/2018/09/10/the-lazy-functor">Lazy</a>, and other functors. This article provides another example. </p> <h3 id="cde6cc0f422941c6a89cc7717f3b62b5"> Functor <a href="#cde6cc0f422941c6a89cc7717f3b62b5" title="permalink">#</a> </h3> <p> In a recent article, I gave an example of <a href="/2020/06/15/io-container-in-a-parallel-c-universe">what <em>IO</em> might look like in C#</a>. The <code>IO&lt;T&gt;</code> <a href="https://bartoszmilewski.com/2014/01/14/functors-are-containers">container</a> already has sufficent API to make it a functor. All it needs is a <code>Select</code> method: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">TResult</span>&gt;&nbsp;Select&lt;<span style="color:#2b91af;">TResult</span>&gt;(<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">T</span>,&nbsp;<span style="color:#2b91af;">TResult</span>&gt;&nbsp;selector) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;SelectMany(x&nbsp;=&gt;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">TResult</span>&gt;(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Lazy</span>&lt;<span style="color:#2b91af;">TResult</span>&gt;(selector(x)))); }</pre> </p> <p> This is an instance method on <code>IO&lt;T&gt;</code>, but you can also write it as an extension method, if that's more to your liking. </p> <p> When you call <code>selector(x)</code>, the return value is an object of the type <code>TResult</code>. The <code>SelectMany</code> method, however, wants you to return an object of the type <code>IO&lt;TResult&gt;</code>, so you use the <code>IO</code> constructor to wrap that return value. </p> <h3 id="0f17690c09b34160a7cc843a461d836d"> Haskell <a href="#0f17690c09b34160a7cc843a461d836d" title="permalink">#</a> </h3> <p> The C# <code>IO&lt;T&gt;</code> container is an illustration of how <a href="https://www.haskell.org">Haskell</a>'s <code>IO</code> type works. It should come as no surprise to Haskellers that <code>IO</code> is a functor. In fact, it's a monad, and all monads are also functors. </p> <p> The C# <code>IO&lt;T&gt;</code> API is based around a constructor and the <code>SelectMany</code> method. The constructor wraps a plain <code>T</code> value in <code>IO&lt;T&gt;</code>, so that corresponds to Haskell's <code>return</code> method. The <code>SelectMany</code> method corresponds to Haskell's monadic <em>bind</em> operator <code>&gt;&gt;=</code>. When you have lawful <code>return</code> and <code>&gt;&gt;=</code> implementations, you can have a <code>Monad</code> instance. When you have a <code>Monad</code> instance, you not only <em>can</em> have <code>Functor</code> and <code>Applicative</code> instances, you <em>must</em> have them. </p> <h3 id="2c8de38e7bd04656855c405529c71908"> Conclusion <a href="#2c8de38e7bd04656855c405529c71908" title="permalink">#</a> </h3> <p> IO forms a functor, among other abstractions. In C#, this manifests as a proper implementation of a <code>Select</code> method. </p> <p> <strong>Next:</strong> <a href="/2018/12/03/set-is-not-a-functor">Set is not a functor</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="a571ffe129e44ddbb2ecec0bf4d108ac"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> The constructor wraps a plain <code>T</code> value in <code>IO&lt;T&gt;</code> </blockquote> <p> Did you mean to say that the constructor wraps a <code>Lazy&lt;T&gt;</code> value in <code>IO&lt;T&gt;</code>? </p> </div> <div class="comment-date">2020-06-22 14:05 UTC</div> </div> <div class="comment" id="6c7f026e825942429254efc19440b2e2"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for writing. Well, yes, that's technically what happens... I'm deliberately being imprecise with the language because I'm trying to draw a parallel to Haskell. In Haskell, <code>return</code> takes a value and wraps it in <code>IO</code> (the type is effectively <code>a -&gt; IO a</code>). In Haskell, however, computation is lazy by default. This means that the value you wrap in <code>IO</code> is already lazy. This turns out to be important, as I'll explain in a future article, so in C# we have to first make sure that the value is lazy. </p> <p> The concept, however, involves taking a 'bare' value and wrapping it in a container, and that's the reason I chose my words as I did. </p> </div> <div class="comment-date">2020-06-22 14:45 UTC</div> </div> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. IO container in a parallel C# universe https://blog.ploeh.dk/2020/06/15/io-container-in-a-parallel-c-universe 2020-06-15T05:55:00+00:00 Mark Seemann <div id="post"> <p> <em>A C# model of IO at the type level.</em> </p> <p> This article is part of <a href="/2020/06/08/the-io-container">an article series about the IO container in C#</a>. The previous article provided a conceptual overview. In this article you'll see C# code examples. </p> <h3 id="03b3ac7f1b2542b583e7f122f1c8da7d"> In a world... <a href="#03b3ac7f1b2542b583e7f122f1c8da7d" title="permalink">#</a> </h3> <p> Imagine a parallel universe where a C# <a href="https://en.wikipedia.org/wiki/Entry_point">entry point</a> is supposed to look like this: </p> <p> <pre><span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">Unit</span>&gt;&nbsp;Main(<span style="color:blue;">string</span>[]&nbsp;args)</pre> </p> <p> Like another Neo, you notice that something in your reality is odd, so you decide to follow the white rabbit. <code>Unit</code>? What's that? Navigating to its definition, you see this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">sealed</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Unit</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Unit</span>&nbsp;Instance; }</pre> </p> <p> There's not much to see here. <code>Unit</code> is a type that serves the same role as the <code>void</code> keyword. <a href="/2018/01/15/unit-isomorphisms">They're isomorphic</a>, but <code>Unit</code> has the advantage that it's a proper type. This means that it can be a type parameter in a generically typed container like <code>IO</code>. </p> <p> So what's <code>IO</code>? When you view its definition, this is what you see: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">sealed</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">T</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IO</span>(<span style="color:#2b91af;">Lazy</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;item); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">TResult</span>&gt;&nbsp;SelectMany&lt;<span style="color:#2b91af;">TResult</span>&gt;(<span style="color:#2b91af;">Func</span>&lt;<span style="color:#2b91af;">T</span>,&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">TResult</span>&gt;&gt;&nbsp;selector); }</pre> </p> <p> There's a constructor you can initialise with a lazily evaluated value, and a <code>SelectMany</code> method that looks strikingly like something out of LINQ. </p> <p> You'll probably notice right away that while you can put a value into the <code>IO</code> container, you can't get it back. As the introductory article explained, this is by design. Still, you may think: <em>What's the point?</em> Why would I ever want to use this class? </p> <p> You get part of the answer when you try to implement your program's entry point. In order for it to compile, the <code>Main</code> method must return an <code>IO&lt;Unit&gt;</code> object. Thus, the simplest <code>Main</code> method that compiles is this: </p> <p> <pre><span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">Unit</span>&gt;&nbsp;Main(<span style="color:blue;">string</span>[]&nbsp;args) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">Unit</span>&gt;(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Lazy</span>&lt;<span style="color:#2b91af;">Unit</span>&gt;(<span style="color:#2b91af;">Unit</span>.Instance)); }</pre> </p> <p> That's only a roundabout <a href="https://en.wikipedia.org/wiki/NOP_(code)">no-op</a>. What if you want write <em>real</em> code? Like <a href="https://en.wikipedia.org/wiki/%22Hello,_World!%22_program">hello world</a>? </p> <h3 id="01dbc48c2136426680432d9b290ed281"> Impure actions <a href="#01dbc48c2136426680432d9b290ed281" title="permalink">#</a> </h3> <p> You'd like to write a program that asks the user about his or her name. Based on the answer, and the time of day, it'll write <em>Hello, Nearth,</em> or <em>Good evening, Kate.</em> You'd like to know how to take user input and write to the standard output stream. In this parallel world, the <code>Console</code> API looks like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Console</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:blue;">string</span>&gt;&nbsp;ReadLine(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">Unit</span>&gt;&nbsp;WriteLine(<span style="color:blue;">string</span>&nbsp;value); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;More&nbsp;members&nbsp;here...</span> }</pre> </p> <p> You notice that both methods return <code>IO</code> values. This immediately tells you that they're impure. This is hardly surprising, since <code>ReadLine</code> is non-deterministic and <code>WriteLine</code> has a side effect. </p> <p> You'll also need the current time of day. How do you get that? </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Clock</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">DateTime</span>&gt;&nbsp;GetLocalTime(); }</pre> </p> <p> Again, <code>IO</code> signifies that the returned <code>DateTime</code> value is impure; it's non-deterministic. </p> <h3 id="7c7d0747805541fbb5c31f4257f5ab6e"> Pure logic <a href="#7c7d0747805541fbb5c31f4257f5ab6e" title="permalink">#</a> </h3> <p> A major benefit of functional programming is the natural <a href="https://en.wikipedia.org/wiki/Separation_of_concerns">separation of concerns</a>; separation of business logic from implementation details (a.k.a. the <a href="https://en.wikipedia.org/wiki/Dependency_inversion_principle">Dependency Inversion Principle</a>). </p> <p> Write the logic of the program as a pure function: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;Greet(<span style="color:#2b91af;">DateTime</span>&nbsp;now,&nbsp;<span style="color:blue;">string</span>&nbsp;name) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Hello&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsMorning(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;morning&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsAfternoon(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;afternoon&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(IsEvening(now)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;greeting&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Good&nbsp;evening&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(<span style="color:blue;">string</span>.IsNullOrWhiteSpace(name)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#a31515;">$&quot;</span>{greeting}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#a31515;">$&quot;</span>{greeting}<span style="color:#a31515;">,&nbsp;</span>{name.Trim()}<span style="color:#a31515;">.&quot;</span>; }</pre> </p> <p> You can tell that this is a pure function from its return type. In this parallel universe, <em>all</em> impure library methods look like the above <code>Console</code> and <code>Clock</code> methods. Thus, by elimination, a method that <em>doesn't</em> return <code>IO</code> is pure. </p> <h3 id="a16d564dc28149eaa462813173276fbd"> Composition <a href="#a16d564dc28149eaa462813173276fbd" title="permalink">#</a> </h3> <p> You have impure actions you can invoke, and a pure piece of logic. You can use <code>ReadLine</code> to get the user's name, and <code>GetLocalTime</code> to get the local time. When you have those two pieces of data, you can call the <code>Greet</code> method. </p> <p> This is where most people run aground. <em>"Yes, but Greet needs a string, but I have an IO&lt;string&gt;. <a href="/2019/02/04/how-to-get-the-value-out-of-the-monad">How do I get the string out of the IO?</a></em> </p> <p> If you've been following the plot so far, you know the answer: <a href="https://en.wikipedia.org/wiki/Mu_(negative)">mu</a>. You don't. You compose all the things with <code>SelectMany</code>: </p> <p> <pre><span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">IO</span>&lt;<span style="color:#2b91af;">Unit</span>&gt;&nbsp;Main(<span style="color:blue;">string</span>[]&nbsp;args) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#2b91af;">Console</span>.WriteLine(<span style="color:#a31515;">&quot;What&#39;s&nbsp;your&nbsp;name?&quot;</span>).SelectMany(_&nbsp;=&gt; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Console</span>.ReadLine().SelectMany(name&nbsp;=&gt; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Clock</span>.GetLocalTime().SelectMany(now&nbsp;=&gt; &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;greeting&nbsp;=&nbsp;<span style="color:#2b91af;">Greeter</span>.Greet(now,&nbsp;name); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#2b91af;">Console</span>.WriteLine(greeting); &nbsp;&nbsp;&nbsp;&nbsp;}))); }</pre> </p> <p> I'm not going to walk through all the details of how this works. There's <a href="https://cleancoders.com/videos/humane-code-real">plenty of monad tutorials out there</a>, but take a moment to contemplate the <code>SelectMany</code> method's <code>selector</code> argument. It takes a <em>plain</em> <code>T</code> value as input, but must return an <code>IO&lt;TResult&gt;</code> object. That's what each of the above lambda expressions do, but that means that <code>name</code> and <code>now</code> are <em>unwrapped values;</em> i.e. <code>string</code> and <code>DateTime</code>. </p> <p> That means that you can call <code>Greet</code> with <code>name</code> and <code>now</code>, which is exactly what happens. </p> <p> Notice that the above lambda expressions are nested. With <a href="/2015/08/03/idiomatic-or-idiosyncratic">idiomatic</a> formatting, they'd exhibit the dreaded <a href="http://wiki.c2.com/?ArrowAntiPattern">arrow shape</a>, but with this formatting, it looks more like the sequential composition that it actually is. </p> <h3 id="03f739d929874049be990b3c90c2d7eb"> Conclusion <a href="#03f739d929874049be990b3c90c2d7eb" title="permalink">#</a> </h3> <p> The code you've seen here all works. The only difference between this hypothetical C# and the real C# is that your <code>Main</code> method can't look like that, and impure library methods don't return <code>IO</code> values. </p> <p> The point of the article isn't to recommend this style of programming. You can't, really, since it relies on the counter-factual assumption that all impure library methods return <code>IO</code>. The point of the article is to explain how a language like <a href="https://www.haskell.org">Haskell</a> uses the type system to distinguish between pure functions and impure actions. </p> <p> Perhaps the code in that <code>Main</code> method isn't the prettiest code you've ever seen, but we can make it a little nicer. That's the topic of the next article in the series. </p> <p> <strong>Next:</strong> <a href="/2020/06/29/syntactic-sugar-for-io">Syntactic sugar for IO</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="c0bb2d1ce63d41adba638e489f926ee1"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> Why is the input of the IO constructor of type <code>Lazy&lt;T&gt;</code> instead of just type <code>T</code>? </p> </div> <div class="comment-date">2020-06-22 12:16 UTC</div> </div> <div class="comment" id="8ff4e7987f3e46f4bffe328ec2706679"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for writing. A future article in this article series will answer that question 😀 </p> </div> <div class="comment-date">2020-06-22 12:25 UTC</div> </div> <div class="comment" id="43ca1bf8d83a4124a4a9ccd33343e864"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> FWIW, the promised article is <a href="/2020/07/06/referential-transparency-of-io">now available</a>. </p> </div> <div class="comment-date">2020-07-06 6:01 UTC</div> </div> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. The IO Container https://blog.ploeh.dk/2020/06/08/the-io-container 2020-06-08T05:53:00+00:00 Mark Seemann <div id="post"> <p> <em>How a type system can distinguish between pure and impure code.</em> </p> <p> <a href="https://en.wikipedia.org/wiki/Referential_transparency">Referential transparency</a> is the foundation of <a href="/2018/11/19/functional-architecture-a-definition">functional architecture</a>. If you categorise all operations into <a href="https://en.wikipedia.org/wiki/Pure_function">pure functions</a> and impure actions, then most other traits associated with functional programming follow. </p> <p> Unfortunately, <a href="/2020/02/24/discerning-and-maintaining-purity">mainstream programming languages don't distinguish between pure functions and impure actions</a>. Identifying pure functions is tricky, and the knowledge is fleeting. What was a pure functions today may become impure next time someone changes the code. </p> <p> Separating pure and impure code is important. It'd be nice if you could automate the process. Perhaps you could run some tests, or, <a href="/2011/04/29/Feedbackmechanismsandtradeoffs">even better</a>, make the compiler do the work. That's what <a href="https://www.haskell.org">Haskell</a> and a few other languages do. </p> <p> In Haskell, the distinction is made with a <a href="https://bartoszmilewski.com/2014/01/14/functors-are-containers">container</a> called <code>IO</code>. This static type enforces the functional interaction law at compile time: pure functions can't invoke impure actions. </p> <h3 id="5bb03bce8e314e7696aefa1800f94637"> Opaque container <a href="#5bb03bce8e314e7696aefa1800f94637" title="permalink">#</a> </h3> <p> Regular readers of this blog know that I often use Haskell to demonstrate principles of functional programming. If you don't know Haskell, however, its ability to guarantee the functional interaction law at compile time may seem magical. It's not. </p> <p> Fortunately, the design is so simple that it's easy to explain the fundamental concept: Results of impure actions are always enclosed in an opaque container called <em>IO</em>. You can think of it as a box with a label. </p> <p> <img src="/content/binary/io-box-with-int-inside.png" alt="A cardboard box with the label 'int inside' on the side."> </p> <p> The label only tells you about the static type of the value inside the box. It could be an <code>int</code>, a <code>DateTime</code>, or your own custom type, say <code>Reservation</code>. While you know what type of value is inside the box, you can't see what's in it, and you can't open it. </p> <h3 id="803d5847d88b4b51bebcecddb2581f3a"> Name <a href="#803d5847d88b4b51bebcecddb2581f3a" title="permalink">#</a> </h3> <p> The container itself is called <code>IO</code>, but don't take the word too literally. While all <a href="https://en.wikipedia.org/wiki/Input/output">I/O (input/output)</a> is inherently impure, other operations that you don't typically think of as I/O is impure as well. Generation of random numbers (including GUIDs) is the most prominent example. Random number generators rely on the system clock, which you <em>can</em> think of as an input device, although I think many programmers don't. </p> <p> I could have called the container <em>Impure</em> instead, but I chose to go with <em>IO</em>, since this is the word used in Haskell. It also has the advantage of being short. </p> <h3 id="8964b332bd1a423ba2f9729d679b6225"> What's in the boooox? <a href="#8964b332bd1a423ba2f9729d679b6225" title="permalink">#</a> </h3> <p> A question frequently comes up: <a href="/2019/02/04/how-to-get-the-value-out-of-the-monad">How do I get the value out of my IO?</a> As always, the answer is <a href="https://en.wikipedia.org/wiki/Mu_(negative)">mu</a>. You don't. You inject the desired behaviour into the container. This goes for all monads, including IO. </p> <p> But naturally you wonder: If you can't see the value inside the IO box then <em>what's the point?</em> </p> <p> The point is to enforce the functional interaction law at the type level. A pure function that calls an impure action will receive a sealed, opaque IO box. There's no API that enables a pure function to extract the contents of the container, so this effectively enforces the rule that pure functions can't call impure actions. </p> <p> The other three types of interactions are still possible. <ul> <li>Pure functions should be able to call pure functions. Pure functions return 'normal' values (i.e. values not hidden in IO boxes), so they can call each other as usual.</li> <li>Impure actions should be able to call pure functions. This becomes possible because you can inject pure behaviour into any monad. You'll see example of that in later articles in this series.</li> <li>Impure actions should be able to call other impure actions. Likewise, you can compose many IO actions into one IO action via the IO API.</li> </ul> When you're outside of all IO boxes, there's no way to open the box, and you can't see its contents. </p> <p> On the other hand, <em>if you're already inside the box</em>, you can see the contents. And there's one additional rule: If you're already inside an IO box, you <em>can</em> open other IO boxes and see their contents! </p> <p> In subsequent articles in this article series, you'll see how all of this manifests as C# code. This article gives a high-level view of the concept. I suggest that you go back and re-read it once you've seen the code. </p> <h3 id="2f29062933db44278c87649c31704c9a"> The many-worlds interpretation <a href="#2f29062933db44278c87649c31704c9a" title="permalink">#</a> </h3> <p> If you're looking for metaphors or other ways to understand what's going on, there's two perspectives I find useful. None of them offer the full picture, but together, I find that they help. </p> <p> A common interpretation of IO is that it's like the box in which you put <a href="https://en.wikipedia.org/wiki/Schr%C3%B6dinger%27s_cat">Schrödinger's cat</a>. <code>IO&lt;Cat&gt;</code> can be viewed as the superposition of the two states of cat (assuming that <code>Cat</code> is basically a <a href="https://en.wikipedia.org/wiki/Tagged_union">sum type</a> with the cases <code>Alive</code> and <code>Dead</code>). Likewise, <code>IO&lt;int&gt;</code> represents the superposition of all 4,294,967,296 32-bit integers, <code>IO&lt;string&gt;</code> the superposition of infinitely many strings, etcetera. </p> <p> Only when you observe the contents of the box does the superposition collapse to a single value. </p> <p> But... you can't observe the contents of an IO box, can you? </p> <h3 id="0f85d7e2346d4805ae05045965f9231d"> The black hole interpretation <a href="#0f85d7e2346d4805ae05045965f9231d" title="permalink">#</a> </h3> <p> The IO container represents an impenetrable barrier between the outside and the inside. It's like a <a href="https://en.wikipedia.org/wiki/Black_hole">black hole</a>. Matter can fall into a black hole, but no information can escape its <a href="https://en.wikipedia.org/wiki/Event_horizon">event horizon</a>. </p> <p> In high school I took cosmology, among many other things. I don't know if the following is still current, but we learned a formula for calculating the density of a black hole, based on its mass. When you input the estimated mass of the universe, the formula suggests a density near vacuum. Wait, what?! Are we actually living inside a black hole? Perhaps. Could there be other universes 'inside' black holes? </p> <p> The analogy to the IO container seems apt. You can't see into a black hole from the outside, but once <a href="https://amzn.to/2BlYK6D">beyond the blue event horizon</a>, you can observe everything that goes on in that interior universe. You can't escape to the original universe, though. </p> <p> As with all metaphors, this one breaks down if you think too much about it. Code running in IO can unpack other IO boxes, even nested boxes. There's no reason to believe that if you're inside a black hole that you can then gaze beyond the event horizon of nested black holes. </p> <h3 id="524b6fbfa7c54eb2b26ec8212b7db64e"> Code examples <a href="#524b6fbfa7c54eb2b26ec8212b7db64e" title="permalink">#</a> </h3> <p> In the next articles in this series, you'll see C# code examples that illustrate how this concept might be implemented. The purpose of these code examples is to give you a sense for how <code>IO</code> works in Haskell, but with more familiar syntax. <ul> <li><a href="/2020/06/15/io-container-in-a-parallel-c-universe">IO container in a parallel C# universe</a></li> <li><a href="/2020/06/29/syntactic-sugar-for-io">Syntactic sugar for IO</a></li> <li><a href="/2020/07/06/referential-transparency-of-io">Referential transparency of IO</a></li> <li>Implementation of the C# IO container</li> <li>Task asynchronous programming as an IO surrogate</li> </ul> These code examples are <em>illustrations</em>, not recommendations. </p> <h3 id="729688b622f64684b3f5ad2816eadaca"> Conclusion <a href="#729688b622f64684b3f5ad2816eadaca" title="permalink">#</a> </h3> <p> When you saw the title, did you think that this would be an article about IoC Containers? It's not. The title isn't a typo, and I never use the term <em>IoC Container</em>. As <a href="https://blogs.cuttingedge.it/steven/">Steven</a> and I explain in <a href="/dippp">our book</a>, <em>Inversion of Control</em> (IoC) is a broader concept than Dependency Injection (DI). It's called a <em>DI Container</em>. </p> <p> IO, on the other hand, is a container of impure values. Its API enables you to 'build' bigger structures (programs) from smaller IO boxes. You can compose IO actions together and inject pure functions into them. The boxes, however, are opaque. Pure functions can't see their contents. This effectively enforces the functional interaction law at the type level. </p> <p> <strong>Next:</strong> <a href="/2020/06/15/io-container-in-a-parallel-c-universe">IO container in a parallel C# universe</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header">Comments</h2> <div class="comment" id="33c7fbbfa5ba409a885296b880592e80"> <div class="comment-author"><a href="https://www.relativisticramblings.com/">Christer van der Meeren</a></div> <div class="comment-content"> <p> Come on, you know there is a perfect metaphor. <a href="https://blog.plover.com/prog/burritos.html">Monads are like burritos.</a> </p> </div> <div class="comment-date">2020-06-08 11:08 UTC</div> </div> <div class="comment" id="d5b99040cf664be5a7b3ae5bfc2b6394"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Christer, I appreciate that this is all in good fun 🤓 </p> <p> For the benefit of readers who may still be trying to learn these concepts, I'll point out that just as this isn't an article about <em>IoC containers</em>, it's not a monad tutorial. It's an explanation of a particular API called <em>IO</em>, which, among other traits, also forms a monad. I'm trying to downplay that aspect here, because I hope that you can understand most of this and the next articles without knowing what a monad is. </p> </div> <div class="comment-date">2020-06-08 11:27 UTC</div> </div> <div class="comment" id="6d8a99b9728b452193311fadec795cf4"> <div class="comment-author"><a href="https://github.com/DunetsNM/">Nick Dunets</a></div> <div class="comment-content"> <p> "While you know what type of value is inside the box, you can't see what's in it, and you can't open it." </p> <p> Well you technically can, with unsafePerformIO ;) although it defeats the whole purpose. </p> </div> <div class="comment-date">2020-06-10 02:31 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Retiring old service versions https://blog.ploeh.dk/2020/06/01/retiring-old-service-versions 2020-06-01T09:36:00+00:00 Mark Seemann <div id="post"> <p> <em>A few ideas on how to retire old versions of a web service.</em> </p> <p> I was recently listening to <a href="https://dotnetrocks.com/?show=1688">a .NET Rocks! episode on web APIs</a>, and one of the topics that came up was how to retire old versions of a web service. It's not easy to do, but not necessarily impossible. </p> <p> The best approach to API versioning is to never break compatibility. As long as there's no breaking changes, you don't have to version your API. It's rarely possible to completely avoid breaking changes, but the fewer of those that you introduce, the fewer API version you have to maintain. I've <a href="/2015/06/22/rest-implies-content-negotiation">previously described how to version REST APIs</a>, but this article doesn't assume any particular versioning strategy. </p> <p> Sooner or later you'll have an old version that you'd like to retire. How do you do that? </p> <h3 id="66f738fcae73491988edafb0eb766001"> Incentives <a href="#66f738fcae73491988edafb0eb766001" title="permalink">#</a> </h3> <p> First, take a minute to understand why some clients keep using old versions of your API. It may be obvious, but I meet enough programmers who never give incentives a thought that I find it worthwhile to point out. </p> <p> When you introduce a breaking change, by definition this is a change that <em>breaks</em> clients. Thus, upgrading from an old version to a newer version of your API is likely to give client developers extra work. If what they have already works to their satisfaction, why should they upgrade their clients? </p> <p> You might argue that your new version is 'better' because it has more features, or is faster, or whatever it is that makes it better. Still, if the old version is good enough for a particular purpose, some clients are going to stay there. The client maintainers have no incentives to upgrade. There's only cost, and no benefit, to upgrading. </p> <p> Even if the developers who maintain those clients would like to upgrade, they may be prohibited from doing so by their managers. If there's no business reason to upgrade, efforts are better used somewhere else. </p> <h3 id="ccca66feb014455288e12ee519c56ada"> Advance warning <a href="#ccca66feb014455288e12ee519c56ada" title="permalink">#</a> </h3> <p> Web services exist in various contexts. Some are only available on an internal network, while others are publicly available on the internet. Some require an authentication token or API key, while others allow anonymous client access. </p> <p> With some services, you have a way to contact every single client developer. With other services, you don't know who uses your service. </p> <p> Regardless of the situation, when you wish to retire a version, you should first try to give clients advance warning. If you have an address list of all client developers, you can simply write them all, but you can't expect that everyone reads their mail. If you don't know the clients, you can publish the warning. If you have a blog or a marketing site, you can publish the warning there. If you run a mailing list, you can write about the upcoming change there. You can tweet it, post it on Facebook, or dance it on TikTok. </p> <p> Depending on SLAs and contracts, there may even be a legally valid communications channel that you can use. </p> <p> Give advance warning. That's the decent thing to do. </p> <h3 id="bfa13823398b42a8aa1f1ef3de2c6b29"> Slow it down <a href="#bfa13823398b42a8aa1f1ef3de2c6b29" title="permalink">#</a> </h3> <p> Even with advance warning, not everyone gets the message. Or, even if everyone got the message, some people deliberately decide to ignore it. Consider their incentives. They may gamble that as long as your logs show that they use the old version, you'll keep it online. What do you do then? </p> <p> You can, of course, just take the version off line. That's going to break clients that still depend on that version. That's rarely the best course of action. </p> <p> Another option is to degrade the performance of that version. Make it slower. You can simply add a constant delay when clients access that service, or you can gradually degrade performance. </p> <p> Many HTTP client libraries have long timeouts. For example, the <a href="https://docs.microsoft.com/dotnet/api/system.net.http.httpclient.timeout">default HttpClient timeout is 100 seconds</a>. Imagine that you want to introduce a gradual performance degradation that starts at no delay on June 1, 2020 and reaches 100 seconds after one year. You can use the formula <code>d = 100 s * (t - t0) / 1 year</code>, where <code>d</code> is the delay, <code>t</code> is the current time, and <code>t0</code> is the start time (e.g. June 1, 2020). This'll cause requests for resources to gradually slow down. After a year, clients still talking to the retiring version will begin to time out. </p> <p> You can think of this as another way to give advance warning. With the gradual deterioration of performance, users will likely notice the long wait times well before calls actually time out. </p> <p> When client developers contact you about the bad performance, you can tell them that the issue is fixed in more recent versions. You've just given the client organisation an incentive to upgrade. </p> <h3 id="741bec1a72bf46cc9e26f6e7600a6fab"> Failure injection <a href="#741bec1a72bf46cc9e26f6e7600a6fab" title="permalink">#</a> </h3> <p> Another option is to deliberately make the service err now and then. Randomly return a <code>500 Internal Server Error</code> from time to time, even if the service <em>can</em> handle the request. </p> <p> Like deliberate performance degradation, you can gradually make the deprecated version more and more unreliable. Again, end users are likely to start complaining about the unreliability of the system long before it becomes entirely useless. </p> <h3 id="bc73620aa71141b6a74f4a4aaf395d75"> Reverse proxy <a href="#bc73620aa71141b6a74f4a4aaf395d75" title="permalink">#</a> </h3> <p> One of the many benefits of HTTP-based services is that you can put a <a href="https://en.wikipedia.org/wiki/Reverse_proxy">reverse proxy</a> in front of your application servers. I've no idea how to configure or operate <a href="https://en.wikipedia.org/wiki/Nginx">NGINX</a> or <a href="https://en.wikipedia.org/wiki/Varnish_(software)">Varnish</a>, but from talking to people who do know, I get the impression that they're quite scriptable. </p> <p> Since the above ideas are independent of actual service implementation or behaviour, it's a generic problem that you should seek to address with general-purpose software. </p> <p> <img src="/content/binary/reverse-proxy-based-delay.png" alt="Sequence diagram of a client, reverse proxy, and application server."> </p> <p> Imagine having a general-purpose reverse proxy that detects whether incoming HTTP requests are for the version you'd like to retire (<em>version 1</em> in the diagram) or another version. If the proxy detects that the request is for a retiring version, it inserts a delay before it forward the request to the application server. For all requests for current versions, it just forwards the request. </p> <p> I could imagine doing something similar with failure injections. </p> <h3 id="a0426537b459414b831db955de4cca26"> Legal ramifications <a href="#a0426537b459414b831db955de4cca26" title="permalink">#</a> </h3> <p> All of the above are only ideas. If you can use them, great. Consider the implications, though. You may be legally obliged to keep an SLA. In that case, you can't degrade the performance or reliability below the SLA level. </p> <p> In any case, I don't think you should do any of these things lightly. Involve relevant stakeholders before you engage in something like the above. </p> <p> Legal specialists are as careful and conservative as traditional operations teams. Their default reaction to any change proposal is to say <em>no</em>. That's not a judgement on their character or morals, but simply another observation based on incentives. As long as everything works as it's supposed to work, any change represents a risk. Legal specialists, like operations teams, are typically embedded in incentive systems that punish risk-taking. </p> <p> To counter other stakeholders' reluctance to engage in unorthodox behaviour, you'll have to explain why retiring an old version of the service is important. It works best if you can quantify the reason. If you can, measure how much extra time you waste on maintaining the old version. If the old version runs on separate hardware, or a separate cloud service, quantify the cost overhead. </p> <p> If you can't produce a compelling argument to retire an old version, then perhaps it isn't that important after all. </p> <h3 id="725c16c05869474a8cf58da8f0705b7e"> Logs <a href="#725c16c05869474a8cf58da8f0705b7e" title="permalink">#</a> </h3> <p> Server logs can be useful. They can tell you how many requests the old version serves, which IP addresses they come from, at which times or dates you have most traffic, and whether the usage trend is increasing or decreasing. </p> <p> These measures can be used to support your argument that a particular version should be retired. </p> <h3 id="226e48b1d4ef4a14bbf778a9fd6983f7"> Conclusion <a href="#226e48b1d4ef4a14bbf778a9fd6983f7" title="permalink">#</a> </h3> <p> Versioning web services is already a complex subject, but once you've figured it out, you'll sooner or later want to retire an old version of your API. If some clients still make good use of that version, you'll have to give them incentive to upgrade to a newer version. </p> <p> It's best if you can proactively make clients migrate, so prioritise amiable solutions. Sometimes, however, you have no way to reach all client developers, or no obvious way to motivate them to upgrade. In those cases, gentle and gradual performance or reliability degradation of deprecated versions could be a way. </p> <p> I present these ideas as nothing more than that: ideas. Use them if they make sense in your context, but think things through. The responsibility is yours. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="c7751c3a6d5b4facbf7a552eeaa62792"> <div class="comment-author"><a href="http://blog.strobaek.org">Karsten Strøbæk</a></div> <div class="comment-content"> <p> Hi Mark. As always an excellent piece. A few comments if I may. </p> <p> An assumption seems to be, that the client is able to update to a new version of the API, but is not inclined to do so for various reasons. I work with organisations where updating a client if nearly impossible. Not because of lack of will, but due to other factors such as government regulations, physical location of client, hardware version or capabilities of said client to name just a few. </p> <p> We have a tendency in the software industry to see updates as a question of 'running Windows update' and then all is good. Most likely because that is the world we live in. If we wish to update a program or even an OS, it is fairly easy even your above considerations taken into account. </p> <p> In the 'physical' world of manufacturing (or pharmacy or mining or ...) the situation is different. The lifetime of the 'thing' running the client is regularly measured in years or even decades and not weeks or months as it is for a piece of software. </p> <p> Updates are often equal to bloating of resource requirements meaning you have to replace the hardware. This might not always be possible again for various reasons. Cost (company is pressed on margin or client is located in Outer Mongolia) or risk (client is located in Syria or some other hotspot) are some I've personally come across. </p> <p> REST/HTTP is not used. I acknowledge that the original podcast from .NET Rocks! was about updating a web service. This does not change the premises of your arguments, but it potentially adds a layer of complication. </p> </div> <div class="comment-date">2020-06-02 14:47 UTC</div> </div> <div class="comment" id="3e0454135e9b49f1b27bec577318484a"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Karsten, thank you for writing. You are correct that the underlying assumption is that you can retire old versions. </p> <p> I, too, have written REST APIs where retiring service versions weren't an option. These were APIs that consumer-grade hardware would communicate with. We had no way to assure that consumers would upgrade their hardware. Those boxes wouldn't have much of a user-interface. Owners might not realise that firmware updates were available, even if they were. </p> <p> This article does, indeed, assume that the reader has made an informed decision that it's fundamentally acceptable to retire a service version. I should have made that more explicit. </p> </div> <div class="comment-date">2020-06-04 5:32 UTC</div> </div> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Where's the science? https://blog.ploeh.dk/2020/05/25/wheres-the-science 2020-05-25T05:50:00+00:00 Mark Seemann <div id="post"> <p> <em>Is a scientific discussion about software development possible?</em> </p> <p> Have you ever found yourself in a heated discussion about a software development topic? Which is best? Tabs or spaces? Where do you put the curly brackets? <a href="/2020/05/04/significant-whitespace-is-dry">Is significant whitespace a good idea?</a> Is Python better than Go? Does test-driven development yield an advantage? <a href="/2019/07/01/yes-silver-bullet">Is there a silver bullet?</a> Can you <a href="https://martinfowler.com/bliki/CannotMeasureProductivity.html">measure software development productivity?</a> </p> <p> I've had plenty of such discussions, and I'll have them again in the future. </p> <p> While some of these discussions may resemble debates on <a href="https://en.wikipedia.org/wiki/How_many_angels_can_dance_on_the_head_of_a_pin%3F">how many angels can dance on the head of a pin</a>, other discussions might be important. Ex ante, it's hard to tell which is which. </p> <p> Why don't we settle these discussions with science? </p> <h3 id="dc849de642834dd998e0fdce57b91550"> A notion of science <a href="#dc849de642834dd998e0fdce57b91550" title="permalink">#</a> </h3> <p> I love science. Why don't I apply scientific knowledge instead of arguments based on <a href="https://martinfowler.com/bliki/AnecdotalEvidence.html">anecdotal evidence</a>? </p> <p> To answer such questions, we must first agree on a definition of science. I favour <a href="https://en.wikipedia.org/wiki/Karl_Popper">Karl Popper</a>'s description of <a href="https://en.wikipedia.org/wiki/Falsifiability">empirical falsifiability</a>. A hypothesis that makes successful falsifiable predictions of the future is a good scientific theory. Such a a theory has <a href="https://en.wikipedia.org/wiki/Predictive_power">predictive power</a>. </p> <p> Newton's theory of gravity had ample predictive power, but Einstein's theory of general relativity supplanted it because its predictive power was even better. </p> <p> <a href="https://en.wikipedia.org/wiki/Gregor_Mendel">Mendel</a>'s theory of inheritance had predictive power, but was refined into what is modern-day genetics which yields much greater predictive power. </p> <p> Is predictive power the only distinguishing trait of good science? I'm already venturing into controversial territory by taking this position. I've met people in the programming community who consider my position naive or reductionist. </p> <p> What about <em>explanatory power?</em> If a theory satisfactorily explains observed phenomena, doesn't that count as a proper scientific theory? </p> <h3 id="080ec1ebb66c498f8d21bfce5939e480"> Controversy <a href="#080ec1ebb66c498f8d21bfce5939e480" title="permalink">#</a> </h3> <p> I don't believe in explanatory power as a sufficient criterion for science. Without predictive power, we have little evidence that an explanation is correct. An explanatory theory can even be internally consistent, and yet we may not know if it describes reality. </p> <p> Theories with explanatory power are the realm of politics or religion. Consider the observation that some people are rich and some are poor. You can believe in a theory that explains this by claiming structural societal oppression. You can believe in another theory that views poor people as fundamentally lazy. Both are (somewhat internally consistent) political theories, but they have yet to demonstrate much predictive power. </p> <p> Likewise, you may believe that some deity created the universe, but that belief produces no predictions. You can apply <a href="https://en.wikipedia.org/wiki/Occam%27s_razor">Occam's razor</a> and explain the same phenomena without a god. A belief in one or more gods is a religious theory, not a scientific theory. </p> <p> It seems to me that there's a correlation between explanatory power and controversy. Over time, theories with predictive power become uncontroversial. Even if they start out controversial (such as Einstein's theory of general relativity), the dust soon settles because it's hard to argue with results. </p> <p> Theories with mere explanatory power, on the other hand, can fuel controversy forever. Explanations can be compelling, and without evidence to refute them, the theories linger. </p> <p> Ironically, you might argue that Popper's theory of scientific discovery itself is controversial. It's a great explanation, but does it have predictive power? Not much, I admit, but I'm also not aware of competing views on science with better predictive power. Thus, you're free to disagree with everything in this article. I admit that it's a piece of philosophy, not of science. </p> <h3 id="1f26035f0b3c40d4b0681a6b2f45176c"> The practicality of experimental verification <a href="#1f26035f0b3c40d4b0681a6b2f45176c" title="permalink">#</a> </h3> <p> We typically see our field of software development as one of the pillars of <a href="https://en.wikipedia.org/wiki/Science,_technology,_engineering,_and_mathematics">STEM</a>. Many of us have STEM educations (I don't; I'm an economist). Yet, we're struggling to come to grips with the lack of scientific methodology in our field. It seems to me that we suffer from <a href="https://en.wikipedia.org/wiki/Physics_envy">physics envy</a>. </p> <p> It's really hard to compete with physics when it comes to predictive power, but even modern physics struggle with experimental verification. Consider an establishment like <a href="https://home.cern">CERN</a>. It takes billions of euros of investment to make today's physics experiments possible. The only reason we make such investments, I think, is that physics so far has had a good track record. </p> <p> What about another fairly 'hard' science like medicine? In order to produce proper falsifiable predictions, medical science have evolved the process of the <a href="https://en.wikipedia.org/wiki/Randomized_controlled_trial">randomised controlled trial</a>. It works well when you're studying short-term effects. Does this medicine cure this disease? Does this surgical procedure improve a patient's condition? How does lack of REM sleep for three days affect your ability to remember strings of numbers? </p> <p> When a doctor tells you that a particular medicine helps, or that surgery might be warranted, he or she is typically on solid scientific grounds. </p> <p> Here's where things start to become less clear, though, What if <a href="https://en.wikipedia.org/wiki/Atkins_diet">a doctor tells you that a particular diet</a> will improve your expected life span? Is he or she on scientific solid ground? </p> <p> That's rarely the case, because you can't make randomised controlled trials about life styles. Or, rather, a totalitarian society might be able to do that, but we'd consider it unethical. Consider what it would involve: You'd have to randomly select a significant number of <em>babies</em> and group them into those who must follow a particular life style, and those who must not. Then you'll somehow have to force those people to stick to their randomly assigned life style for the entirety of their lives. This is not only unethical, but the experiment also takes the most of a century to perform. </p> <p> What life-style scientists instead do is resort to demographic studies, with all the problems of statistics they involve. Again, the question is whether scientific theories in this field offer predictive power. Perhaps they do, but it takes decades to evaluate the results. </p> <p> My point is that medicine isn't exclusively a hard science. Some medicine is, and some is closer to social sciences. </p> <p> I'm an economist by education. Economics is generally not considered a hard science, although it's a field where it's trivial to make falsifiable predictions. Almost all of economics is about numbers, so making a falsifiable prediction is trivial: <em>The MSFT stock will be at 200 by January 1 2021. The unemployment rate in Denmark will be below 5% in third quarter of 2020.</em> The problem with economics is that most of such predictions turn out to be no better than the toss of a coin - even when made by economists. You can make falsifiable predictions in economics, but most of them do, in fact, get falsified. </p> <p> On the other hand, with the advances in such disparate fields as DNA forensics, satellite surveys, and computer-aided image processing, a venerable 'art' like archaeology is gaining predictive power. <em>We predict that if we dig here, we'll find artefacts from the iron age. We predict that if we make a DNA test of these skeletal remains, they'll show that the person buried was a middle-aged women.</em> And so on. </p> <p> One thing is the ability to produce falsifiable predictions. Another things is whether or not the associated experiment is practically possible. </p> <h3 id="1dda923d8e8f4eecbf6cdd79cdc0e27c"> The science of software development <a href="#1dda923d8e8f4eecbf6cdd79cdc0e27c" title="permalink">#</a> </h3> <p> Do we have a science of software development? I don't think that we have. </p> <p> There's <a href="https://en.wikipedia.org/wiki/Computer_science">computer science</a>, but that's not quite the same. That field of study has produced many predictions that hold. <em>In general, <a href="https://en.wikipedia.org/wiki/Quicksort">quicksort</a> will be faster than <a href="https://en.wikipedia.org/wiki/Bubble_sort">bubble sort</a>. There's an algorithm for finding the shortest way through a network.</em> That sort of thing. </p> <p> You will notice that these result are hardly controversial. It's not those topics that we endlessly debate. </p> <p> We debate whether certain ways to organise work is more 'productive'. The entire productivity debate revolves around an often implicit context: that what we discuss is long-term productivity. We don't much argue how to throw together something during a weekend hackaton. We argue whether we can complete a nine-month software project safer with test-driven development. We argue whether a code base can better sustain its organisation year after year if it's written in <a href="https://fsharp.org">F#</a> or JavaScript. </p> <p> There's <a href="https://www.goodreads.com/review/show/1956107880">little scientific evidence on those questions</a>. </p> <p> The main problem, as I see it, is that it's impractical to perform experiments. Coming up with falsifiable predictions is easy. </p> <p> Let's consider an example. Imagine that your hypothesis is that test-driven development makes you more productive in the middle and long run. You'll have to turn that into a falsifiable claim, so first, pick a software development project of sufficient complexity. Imagine that you can find a project that someone estimates will take around ten months to complete for a team of five people. This has to be a real project that someone needs done, complete with vague, contradictory, and changing requirements. Now you formulate your falsifiable prediction, for example: <em>"This project will be delivered one month earlier with test-driven development."</em> </p> <p> Next, you form teams to undertake the work. One team to perform the work <em>with</em> test-driven development, and one team to do the work without it. Then you measure when they're done. </p> <p> This is already impractical, because who's going to pay for two teams when one would suffice? </p> <p> Perhaps, if you're an exceptional proposal writer, you could get a research grant for that, but alas, that wouldn't be good enough. </p> <p> With two competing teams of five people each, it might happen that <a href="/2019/09/30/10x-developers">one team member exhibits productivity orders of magnitudes different from the others</a>. That could skew the experimental outcome, so you'd have to go for a proper randomised controlled trial. This would involve picking numerous teams and assigning a methodology at random: either they do test-driven development, or they don't. Nothing else should vary. They should all use the same programming language, the same libraries, the same development tools, and work the same hours. Furthermore, no-one outside the team should know which teams follow which method. </p> <p> Theoretically possible, but impractical. It would require finding and paying many software teams for most of a year. One such experiment would cost millions of euros. </p> <p> If you did such an experiment, it would tell you something, but it'd still be open to interpretation. You might argue that the programming language used caused the outcome, but that one can't extrapolate from that result to other languages. Or perhaps there was something special about the project that you think doesn't generalise. Or perhaps you take issue with the pool from which the team members were drawn. You'd have to repeat the experiment while varying one of the other dimensions. That'll cost millions more, and take another year. </p> <p> Considering the billions of euros/dollars/pounds the world's governments pour into research, you'd think that we could divert a few hundred millions to do proper research in software development, but it's unlikely to happen. That's the reason we have to contend ourselves with arguing from anecdotal evidence. </p> <h3 id="6af72b5a24aa4caba250da2373a975d9"> Conclusion <a href="#6af72b5a24aa4caba250da2373a975d9" title="permalink">#</a> </h3> <p> I can imagine how scientific inquiry into software engineering could work. It'd involve making a falsifiable prediction, and then set up an experiment to prove it wrong. Unfortunately, to be on a scientifically sound footing, experiments should be performed with randomised controlled trials, with a statistically significant number of participants. It's not too hard to conceive of such experiments, but they'd be prohibitively expensive. </p> <p> In the meantime, the software development industry moves forward. We share ideas and copy each other. Some of us are successful, and some of us fail. Slowly, this might lead to improvements. </p> <p> That process, however, looks more like evolution than scientific progress. The fittest software development organisations survive. They need not be the best, as they could be stuck in local maxima. </p> <p> When we argue, when we write blog posts, when we speak at conferences, when we appear on podcasts, we exchange ideas and experiences. Not genes, but <a href="https://en.wikipedia.org/wiki/Meme">memes</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="5eec3680e62d40ca8d6e6ab7cc3cf34f"> <div class="comment-author">Sergey Petrov</div> <div class="comment-content"> <p> That topic is something many software developers think about, at least I do from time to time. </p> <p> Your post reminded me of that conference talk <a href="https://www.youtube.com/watch?v=WELBnE33dpY">Intro to Empirical Software Engineering: What We Know We Don't Know</a> by Hillel Wayne. Just curious - have you seen the talk and if so - what do you think? Researches mentioned in the talk are not proper scientific expreiments as you describe, but anyway looked really interesting to me. </p> </div> <div class="comment-date">2020-05-28 12:40 UTC</div> </div> <div class="comment" id="c223fed5e0294187a5faaca6c885d945"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Sergey, thank you for writing. I didn't know about that talk, but Hillel Wayne regularly makes an appearance in my Twitter feed. I've now seen the talk, and I think it offers a perspective close to mine. </p> <p> I've already read <em>The Leprechauns of Software Engineering</em> (above, I linked to my review), but while I was aware of <a href="https://amzn.to/2XQPHSV">Making Software</a>, I've yet to read it. Several people have reacted to my article by recommending that book, so it's now on it's way to me in the mail. </p> </div> <div class="comment-date">2020-06-02 10:26 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Modelling versus shaping reality https://blog.ploeh.dk/2020/05/18/modelling-versus-shaping-reality 2020-05-18T07:08:00+00:00 Mark Seemann <div id="post"> <p> <em>How does software development relate to reality?</em> </p> <p> I recently <a href="https://dotnetrocks.com/?show=1685">appeared as a guest on the <em>.NET Rocks!</em> podcast</a> where we discussed <a href="https://en.wikipedia.org/wiki/Fred_Brooks">Fred Brooks</a>' 1986 essay <a href="https://en.wikipedia.org/wiki/No_Silver_Bullet">No Silver Bullet</a>. As a reaction, <a href="https://jonsmusings.com">Jon Suda</a> wrote <a href="https://jonsmusings.com/Full-Silver-Jacket">a thoughtful piece of his own</a>. That made me think some more. </p> <h3 id="80fd2177df7e4569a292b795ec32a1a3"> Beware of Greeks... <a href="#80fd2177df7e4569a292b795ec32a1a3" title="permalink">#</a> </h3> <p> Brooks' central premise is <a href="https://en.wikipedia.org/wiki/Aristotle">Aristotle</a>'s distinction between <em>essential</em> and <em>accidental</em> complexity. I've already examined the argument in <a href="/2019/07/01/yes-silver-bullet">my previous article on the topic</a>, but in summary, Brooks posits that complexity in software development can be separated into those two categories: </p> <p> <pre>c = E + a</pre> </p> <p> Here, <code>c</code> is the total complexity, <code>E</code> is the essential complexity, and <code>a</code> the accidental complexity. I've deliberately represented <code>c</code> and <code>a</code> with lower-case letters to suggest that they represent variables, whereas I mean to suggest with the upper-case <code>E</code> that the essential complexity is constant. That's Brooks' argument: Every problem has an essential complexity that can't be changed. Thus, your only chance to reduce total complexity <code>c</code> is to reduce the accidental complexity <code>a</code>. </p> <p> Jon Suda writes that <blockquote> <p> "Mark doesn’t disagree with the classification of problems" </p> <footer><cite><a href="https://jonsmusings.com/Full-Silver-Jacket">Jon Suda</a></cite></footer> </blockquote> That got me thinking, because actually I do. When I wrote <a href="/2019/07/01/yes-silver-bullet">Yes silver bullet</a> I wanted to engage with Brooks' essay on its own terms. </p> <p> I do think, however, that one should be sceptical of any argument originating from the ancient Greeks. These people believed that all matter was composed of <a href="https://en.wikipedia.org/wiki/Classical_element">earth, water, air, and fire</a>. They believed in the <a href="https://en.wikipedia.org/wiki/Emission_theory_(vision)">extramission theory of vision</a>. They practised medicine by <a href="https://en.wikipedia.org/wiki/Humorism">trying to balance blood, phlegm, yellow, and black bile</a>. Aristotle believed in <a href="https://en.wikipedia.org/wiki/Spontaneous_generation">spontaneous generation</a>. He also <a href="https://en.wikipedia.org/wiki/History_of_neuroscience">believed that the brain was a radiator while the heart was the seat of intelligence</a>. </p> <p> I think that Aristotle's distinction between essential and accidental complexity is a <a href="https://en.wikipedia.org/wiki/False_dilemma">false dichotomy</a>, at least in the realm of software development. </p> <p> The problem is the assumption that there's a single, immutable underlying reality to be modelled. </p> <h3 id="006f597e772546c2a1083d98ec21f87c"> Modelling reality <a href="#006f597e772546c2a1083d98ec21f87c" title="permalink">#</a> </h3> <p> Jon Suda touches on this as well: <blockquote> <p> "Conceptual (or business) problems are rooted in the problem domain (i.e., the real world)[...]" </p> <p> "Dealing with the "messy real world" is what makes software development hard these days" </p> <footer><cite><a href="https://jonsmusings.com/Full-Silver-Jacket">Jon Suda</a></cite></footer> </blockquote> I agree that the 'real world' (whatever it is) is often messy, and our ability to deal with the mess is how we earn our keep. It seems to me, though, that there's an underlying assumption that there's a single real world to be modelled. </p> <p> I think that a more fruitful perspective is to question that assumption. <a href="http://udidahan.com/2012/03/05/dont-try-to-model-the-real-world-it-doesnt-exist">Don’t try to model the real world, it doesn’t exist.</a> </p> <p> I've mostly worked with business software. Web shops, <a href="https://twitter.com/ploeh/status/530320252790669313">BLOBAs</a>, and other software to support business endeavours. This is the realm implicitly addressed by <a href="http://amzn.to/WBCwx7">Domain-Driven Design</a> and a technique like <a href="https://en.wikipedia.org/wiki/Behavior-driven_development">behaviour-driven development</a>. The assumption is that there's one or more <em>domain experts</em> who know how the business operates, and the job of the software development team is to translate that understanding into working software. </p> <p> This is often the way it happens. Lord knows that I've been involved in enough fixed-requirements contracts to know that sometimes, all you can do is try to implement the requirements as best you can, regardless of how messy they are. In other words, I agree with Jon Suda that messy problems are a reality. </p> <p> Where I disagree with Brooks and Aristotle is that business processes contain essential complexity. In the old days, before computers, businesses ran according to a set of written and unwritten rules. Routine operations might be fairly consistent, but occasionally, something out of the ordinary would happen. Organisations don't have a script for every eventuality. When the unexpected happens, people wing it. </p> <p> A business may have a way it sells its goods. It may have a standard price list, and a set of discounts that salespeople are authorised to offer. It may have standard payment terms that customers are expected to comply with. It may even have standard operating procedures for dealing with missing payments. </p> <p> Then one day, say, the German government expresses interest in placing an order greater than the business has ever handled before. The Germans, however, want a special discount, and special terms of payment. What happens? Do the salespeople refuse because those requests don't comply with the way the organisation does business? Of course not. The case is escalated to people with the authority to change the rules, and a deal is made. </p> <p> Later, the French government comes by, and a similar situation unfolds, but with the difference that someone else handles the French, and the deal struck is different. </p> <p> The way these two cases are handled could be internally inconsistent. Decisions are made based on concrete contexts, but with incomplete information and based on gut feelings. </p> <p> While there may be a system to how an organisation does routine business, there's no uniform reality to be modelled. </p> <p> You can model standard operating procedures in software, but I think it's a mistake to think that it's a model of reality. It's just an interpretation on how routine business is conducted. </p> <p> There's no single, unyielding essential complexity, because the essence isn't there. </p> <h3 id="e9af89838d33486d8c983b50e154e389"> Shaping reality <a href="#e9af89838d33486d8c983b50e154e389" title="permalink">#</a> </h3> <p> <a href="https://www.infoq.com/presentations/Fowler-North-Crevasse-of-Doom">Dan North tells a story</a> of a project where a core business requirement was the ability to print out data. When investigating the issue, it turned out that users needed to have the printout next to their computers so that they could type the data into another system. When asked whether they wouldn't rather prefer to have the data just appear in the other system, they incredulously replied, <em>"You can do that?!</em> </p> <p> <a href="https://twitter.com/ploeh/status/1259832000095059968">This turns out to be a common experience</a>. Someone may tell you about an essential requirement, but when you investigate, it turns out to be not at all essential. There may not be any essential complexity. </p> <p> There's likely to be complexity, but the distinction between essential and accidental complexity seems artificial. While software can model business processes, it can also shape reality. Consider a company like Amazon. The software that supports Amazon wasn't developed <em>after</em> the company was already established. Amazon developed it concurrently with setting up business. </p> <p> Consider companies like Google, Facebook, Uber, or Airbnb. Such software doesn't model reality; it <em>shapes</em> reality. </p> <p> In the beginning of the IT revolution, the driving force behind business software development was to automate existing real-world processes, but this is becoming increasingly rare. New companies enter the markets digitally born. Older organisations may be on their second or third system since they went digital. Software not only models 'messy' reality - it shapes 'messy' reality. </p> <h3 id="8b73389dded94ac593f577969cbdfbea"> Conclusion <a href="#8b73389dded94ac593f577969cbdfbea" title="permalink">#</a> </h3> <p> It may look as though I fundamentally disagree with Jon Suda's blog post. I don't. I agree with almost all of it. It did, however, inspire me to put my thoughts into writing. </p> <p> My position is that I find the situation more nuanced than Fred Brooks suggests by setting off from Aristotle. I don't think that the distinction between essential and accidental complexity is the whole story. Granted, it provides a fruitful and inspiring perspective, but while we find it insightful, we shouldn't accept it as gospel. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="10c9a14dbcd64f28835e7c136d4f9a93"> <div class="comment-author"><a href="https://jonsmusings.com/">Jon Suda</a></div> <div class="comment-content"> <p> I think I agree with virtually everything said here – if not <em>actually</em> everything 😊 </p> <p> As (virtually, if not <em>actually</em>) always, though, there are a few things I’d like to add, clarify, and elaborate on 😊 </p> <p> I fully share your reluctance to accept ancient Greek philosophy. I once discussed No Silver Bullet (and drank Scotch) with a (non-developer) “philosopher” friend of mine. (Understand: He has a BA in philosophy 😊) He said something to the effect of <em>do you understand this essence/accident theory is considered obsolete?</em> I answered that it was beside the point here – at least as far as I was concerned. For me, the dichotomy serves as an inspiration, a metaphor perhaps, not a rigorous theoretical framework – that’s one of the reasons why I adapted it into the (informal) conceptual/technical distinction. </p> <p> I also 100% agree with the notion that software shouldn’t merely “model” or “automate” reality. In fact, I now remember that back in university, this was one of the central themes of my “thesis” (or whatever it was). I pondered the difference/boundary between analysis and design activities and concluded that the idea of creating a model of the “real world” during analysis and then building a technical representation of this model as part of design/implementation couldn’t adequately describe many of the more “inventive” software projects and products. </p> <p> I don’t, however, believe this makes the conceptual/technical (essential/accidental) distinction go away. Even though the point of a project may not (and should not) be a mere automation of a preexisting reality, you still need to know what you want to achieve (i.e., “invent”), <em>conceptually</em>, to be able to fashion a <em>technical</em> implementation of it. And yes, your conceptual model should be based on what’s possible with all available technology – which is why you’ll hopefully end up with something <em>way</em> better than the old solution. (Note that in my post, I never talk about “modeling” the “messy real world” but rather “dealing with it”; even your revolutionary new solution will have to coexist with the messy outside world.) </p> <p> For me, one of the main lessons of No Silver Bullet, the moral of the story, is this: Developers tend to spend inordinate amounts of time discussing and brooding over geeky technical stuff; perhaps they should, instead, talk to their users a bit more and learn something about the problem domain; that’s where the biggest room for improvement is, in my opinion. </p> </div> <div class="comment-date">2020-05-20 16:40 UTC</div> </div> <div class="comment" id="15e5f7c1886343cdbde0bcd30f7cfbc4"> <div class="comment-author"><a href="https://jonsmusings.com/">Jon Suda</a></div> <div class="comment-content"> <p> FWIW </p> <p> <a href="https://jonsmusings.com/Transmutation-of-Reality">https://jonsmusings.com/Transmutation-of-Reality</a> </p> <p> Let the inspiration feedback loop continue 😊 I agree with more-or-less everything you say; I just don’t necessarily think that your ideas are incompatible with those expressed in No Silver Bullet. That, to a significant extent (but not exclusively), is what my new post is about. As I said in my previous comment, your article reminded me of my university “thesis,” and I felt that the paper I used as its “conceptual framework” was worth presenting in a “non-academic” form. It can mostly be used to support your arguments – I certainly use it that way. </p> </div> <div class="comment-date">2020-05-29 17:28 UTC</div> </div> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. AFK https://blog.ploeh.dk/2020/05/11/afk 2020-05-11T07:04:00+00:00 Mark Seemann <div id="post"> <p> <em>Software development productivity tip: regularly step away from the computer.</em> </p> <p> In these days of covid-19, people are learning that productivity is imperfectly correlated to the amount of time one is physically present in an office. Indeed, the time you spend in front of you computer is hardly correlated to your productivity. After all, <a href="/2018/09/17/typing-is-not-a-programming-bottleneck">programming productivity isn't measured by typing speed</a>. Additionally, you can waste much time at the computer, checking Twitter, watching cat videos on YouTube, etc. </p> <h3 id="63ec07d591da4ac0b8f47501ba65eb6a"> Pomodorobut <a href="#63ec07d591da4ac0b8f47501ba65eb6a" title="permalink">#</a> </h3> <p> I've worked from home for years, so I thought I'd share some productivity tips. I only report what works for me. If you can use some of the tips, then great. If they're not for you, that's okay too. I don't pretend that I've found any secret sauce or universal truth. </p> <p> A major problem with productivity is finding the discipline to work. I use <em>Pomodorobut</em>. It's like <a href="https://www.scrum.org/resources/what-scrumbut">Scrumbut</a>, but for the <a href="https://en.wikipedia.org/wiki/Pomodoro_Technique">Pomodoro technique</a>. For years I thought I was using the Pomodoro technique, but <a href="https://twitter.com/arialdomartini/status/1238426025429794818">Arialdo Martini makes a compelling case that I'm not</a>. He suggests just calling it <em>timeboxing</em>. </p> <p> I think it's a little more than that, though, because the way I use Pomodorobut has two equally important components: <ul> <li>The 25-minute work period</li> <li>The 5-minute break</li> </ul> The 25 minutes is a sufficiently short period that even if you loathe the task ahead of you, you can summon the energy to do it for 25 minutes. Once you get started, it's usually not that bad. </p> <p> When you program, you often run into problems: <ul> <li>There's a bug that you don't understand.</li> <li>You can't figure out the correct algorithm to implement a particular behaviour.</li> <li>Your code doesn't compile, and you don't understand why.</li> <li>A framework behaves inexplicably.</li> </ul> When you're in front of your computer, you can be stuck at such problems for hours on end. </p> <p> The solution: take a break. </p> <h3 id="402a30606d684e179e8a0379c967a31a"> Breaks give a fresh perspective <a href="#402a30606d684e179e8a0379c967a31a" title="permalink">#</a> </h3> <p> I take my Pomodorobut breaks seriously. My rule is that I must leave my office during the break. I usually go get a glass of water or the like. The point is to get out of the chair and <em>afk</em> (away from keyboard). </p> <p> While I'm out the room, it often happens that I get an insight. If I'm stuck on something, I may think of a potential solution, or I may realise that the problem is irrelevant, because of a wider context I forgot about when I sat in front of the computer. </p> <p> You may have heard about <a href="https://en.wikipedia.org/wiki/Rubber_duck_debugging">rubber ducking</a>. Ostensibly <blockquote> <p> "By having to verbalize [...], you may suddenly gain new insight into the problem." </p> <footer><cite><a href="http://bit.ly/the-pragmatic-programmer">Andy Hunt and Dave Thomas</a></cite></footer> </blockquote> I've tried it enough times: you ask a colleague if he or she has a minute, launch into an explanation of your problem, only to break halfway through and say: <em>"Never mind! I suddenly realised what the problem is. Thank you for your help."</em> </p> <p> Working from home, I haven't had a colleague I could disturb like that for years, and I don't actually use a rubber duck. In my experience, getting out of my chair works equally well. </p> <p> The Pomodorobut technique makes me productive because the breaks, and the insights they spark, reduce the time I waste on knotty problems. When I'm in danger of becoming stuck, I often find a way forward in less than 30 minutes: at most 25 minutes being stuck, and a 5-minute break to get unstuck. </p> <h3 id="814a2859670247dc8add4a6d1a2cd29c"> Hammock-driven development <a href="#814a2859670247dc8add4a6d1a2cd29c" title="permalink">#</a> </h3> <p> Working from home gives you extra flexibility. I have a regular routine where I go for a run around 10 in the morning. I also routinely go grocery shopping around 14 in the afternoon. Years ago, when I still worked in an office, I'd ride my bicycle to and from work every day. I've had my good ideas during those activities. </p> <p> In fact, I can't recall ever having had a profound insight in front of the computer. They always come to me when I'm away from it. For instance, I distinctly remember walking around in my apartment doing other things when I realised that <a href="/2018/06/25/visitor-as-a-sum-type">the Visitor design pattern is just another encoding of a sum type</a>. </p> <p> Insights don't come for free. As Rich Hickey points out in his talk about <a href="https://youtu.be/f84n5oFoZBc">hammock-driven development</a>, you must feed your 'background mind'. That involves deliberate focus on the problem. </p> <p> Good ideas don't come if you're permanently away from the computer, but neither do they arrive if all you do is stare at the screen. It's the variety that makes you productive. </p> <h3 id="3bcce686b9ed4deba31c7e9f7bb27893"> Conclusion <a href="#3bcce686b9ed4deba31c7e9f7bb27893" title="permalink">#</a> </h3> <p> Software development productivity is weakly correlated with the time you spend in front of the computer. I find that I'm most productive when I can vary my activities during the day. Do a few 25-minute sessions, rigidly interrupted by breaks. Go for a run. Work a bit more on the computer. Have lunch. Do one or two more time-boxed sessions. Go grocery shopping. Conclude with a final pair of work sessions. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Significant whitespace is DRY https://blog.ploeh.dk/2020/05/04/significant-whitespace-is-dry 2020-05-04T10:02:00+00:00 Mark Seemann <div id="post"> <p> <em>Languages with explicit scoping encourage you to repeat yourself.</em> </p> <p> When the talk falls on significant whitespace, the most common reaction I hear seems to be one of nervous <a href="https://en.wikipedia.org/wiki/Apotropaic_magic">apotropaic</a> deflection. <blockquote> <p> "Indentation matters? Oh, no! I'm horrified." </p> <footer><cite><a href="https://dotnetrocks.com/?show=1665">Carl Franklin</a></cite></footer> </blockquote> I've always wondered why people react like that. What's the problem with significant whitespace? </p> <p> If given a choice, I'd <em>prefer</em> indentation to matter. In that way, I don't have to declare scope more than once. </p> <h3 id="d4077d55ab644786b54672af077f4729"> Explicit scope <a href="#d4077d55ab644786b54672af077f4729" title="permalink">#</a> </h3> <p> If you had to choose between the following three C# implementations of the <a href="http://codingdojo.org/kata/FizzBuzz/">FizzBuzz kata</a>, which one would you choose? </p> <p> <em>a:</em> </p> <p> <pre><span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Program</span> { <span style="color:blue;">static</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="color:#74531f;">Main</span>() { <span style="font-weight:bold;color:#8f08c4;">for</span>&nbsp;(<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;=&nbsp;1;&nbsp;<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;&lt;&nbsp;100;&nbsp;<span style="font-weight:bold;color:#1f377f;">i</span>++) { <span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;%&nbsp;15&nbsp;==&nbsp;0) { <span style="color:#2b91af;">Console</span>.<span style="color:#74531f;">WriteLine</span>(<span style="color:#a31515;">&quot;FizzBuzz&quot;</span>); } <span style="font-weight:bold;color:#8f08c4;">else</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;%&nbsp;3&nbsp;==&nbsp;0) { <span style="color:#2b91af;">Console</span>.<span style="color:#74531f;">WriteLine</span>(<span style="color:#a31515;">&quot;Fizz&quot;</span>); } <span style="font-weight:bold;color:#8f08c4;">else</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;%&nbsp;5&nbsp;==&nbsp;0) { <span style="color:#2b91af;">Console</span>.<span style="color:#74531f;">WriteLine</span>(<span style="color:#a31515;">&quot;Buzz&quot;</span>); } <span style="font-weight:bold;color:#8f08c4;">else</span> { <span style="color:#2b91af;">Console</span>.<span style="color:#74531f;">WriteLine</span>(<span style="font-weight:bold;color:#1f377f;">i</span>); } } } }</pre> </p> <p> <em>b:</em> </p> <p> <pre><span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Program</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="color:#74531f;">Main</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">for</span>&nbsp;(<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;=&nbsp;1;&nbsp;<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;&lt;&nbsp;100;&nbsp;<span style="font-weight:bold;color:#1f377f;">i</span>++) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;%&nbsp;15&nbsp;==&nbsp;0) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Console</span>.<span style="color:#74531f;">WriteLine</span>(<span style="color:#a31515;">&quot;FizzBuzz&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">else</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;%&nbsp;3&nbsp;==&nbsp;0) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Console</span>.<span style="color:#74531f;">WriteLine</span>(<span style="color:#a31515;">&quot;Fizz&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">else</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;%&nbsp;5&nbsp;==&nbsp;0) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Console</span>.<span style="color:#74531f;">WriteLine</span>(<span style="color:#a31515;">&quot;Buzz&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">else</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Console</span>.<span style="color:#74531f;">WriteLine</span>(<span style="font-weight:bold;color:#1f377f;">i</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> <em>c:</em> </p> <p> <pre><span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Program</span>&nbsp;{&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="color:#74531f;">Main</span>()&nbsp;{&nbsp;<span style="font-weight:bold;color:#8f08c4;">for</span>&nbsp;(<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;=&nbsp;1;&nbsp;<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;&lt;&nbsp;100;&nbsp;<span style="font-weight:bold;color:#1f377f;">i</span>++)&nbsp;{&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;%&nbsp;15&nbsp;==&nbsp;0)&nbsp;{&nbsp;<span style="color:#2b91af;">Console</span>.<span style="color:#74531f;">WriteLine</span>(<span style="color:#a31515;">&quot;FizzBuzz&quot;</span>);&nbsp;}&nbsp;<span style="font-weight:bold;color:#8f08c4;">else</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;%&nbsp;3&nbsp;==&nbsp;0)&nbsp;{&nbsp;<span style="color:#2b91af;">Console</span>.<span style="color:#74531f;">WriteLine</span>(<span style="color:#a31515;">&quot;Fizz&quot;</span>);&nbsp;}&nbsp;<span style="font-weight:bold;color:#8f08c4;">else</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;%&nbsp;5&nbsp;==&nbsp;0)&nbsp;{&nbsp;<span style="color:#2b91af;">Console</span>.<span style="color:#74531f;">WriteLine</span>(<span style="color:#a31515;">&quot;Buzz&quot;</span>);&nbsp;}&nbsp;<span style="font-weight:bold;color:#8f08c4;">else</span>&nbsp;{&nbsp;<span style="color:#2b91af;">Console</span>.<span style="color:#74531f;">WriteLine</span>(<span style="font-weight:bold;color:#1f377f;">i</span>);&nbsp;}&nbsp;}&nbsp;}&nbsp;}</pre> </p> <p> Which of these do you prefer? <em>a</em>, <em>b</em>, or <em>c?</em> </p> <p> You prefer <em>b.</em> Everyone does. </p> <p> Yet, those three examples are equivalent. Not only do they behave the same - except for whitespace, they're identical. They produce the same effective abstract syntax tree. </p> <p> Even though a language like C# has explicit scoping and statement termination with its curly brackets and semicolons, indentation still matters. It doesn't matter to the compiler, but it matters to humans. </p> <p> When you format code like option <em>b</em>, you express scope twice. Once for the compiler, and once for human readers. You're repeating yourself. </p> <h3 id="f0433a7047ca4809ae347082f9ca6726"> Significant whitespace <a href="#f0433a7047ca4809ae347082f9ca6726" title="permalink">#</a> </h3> <p> Some languages dispense with the <a href="/2019/12/16/zone-of-ceremony">ceremony</a> and let indentation indicate scope. The most prominent is <a href="https://www.python.org">Python</a>, but I've more experience with <a href="https://fsharp.org">F#</a> and <a href="https://www.haskell.org">Haskell</a>. In F#, you could write FizzBuzz like this: </p> <p> <pre>[&lt;EntryPoint&gt;] <span style="color:blue;">let</span>&nbsp;main&nbsp;argv&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">for</span>&nbsp;i&nbsp;<span style="color:blue;">in</span>&nbsp;[1..100]&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;i&nbsp;%&nbsp;15&nbsp;=&nbsp;0&nbsp;<span style="color:blue;">then</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printfn&nbsp;<span style="color:#a31515;">&quot;FizzBuzz&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:blue;">if</span>&nbsp;i&nbsp;%&nbsp;3&nbsp;=&nbsp;0&nbsp;<span style="color:blue;">then</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printfn&nbsp;<span style="color:#a31515;">&quot;Fizz&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:blue;">if</span>&nbsp;i&nbsp;%&nbsp;5&nbsp;=&nbsp;0&nbsp;<span style="color:blue;">then</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printfn&nbsp;<span style="color:#a31515;">&quot;Buzz&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printfn&nbsp;<span style="color:#a31515;">&quot;%i&quot;</span>&nbsp;i &nbsp;&nbsp;&nbsp;&nbsp;0</pre> </p> <p> You don't have to explicitly scope variables or expressions. The scope is automatically indicated by the indentation. You <a href="https://en.wikipedia.org/wiki/Don%27t_repeat_yourself">don't repeat yourself</a>. Scope is expressed once, and both compiler and human understand it. </p> <p> I've programmed in F# for a decade now, and I don't find its use of significant whitespace to be a problem. I'd recommend, however, to turn on the feature in your IDE of choice that shows whitespace characters. </p> <h3 id="31e1f00baf044bab8504cf4e2a492773"> Summary <a href="#31e1f00baf044bab8504cf4e2a492773" title="permalink">#</a> </h3> <p> Significant whitespace is a good language feature. You're going to indent your code anyway, so why not let the indentation carry meaning? In that way, you don't repeat yourself. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. An F# implementation of the Maître d' kata https://blog.ploeh.dk/2020/04/27/an-f-implementation-of-the-maitre-d-kata 2020-04-27T14:41:00+00:00 Mark Seemann <div id="post"> <p> <em>This article walks you through the Ma&icirc;tre d' kata done in F#.</em> </p> <p> In a previous article, I presented <a href="/2020/01/27/the-maitre-d-kata">the Ma&icirc;tre d' kata</a> and promised to publish a walkthrough. Here it is. </p> <h3 id="f7bc269790014e9d9510c4c034e9a1bb"> Preparation <a href="#f7bc269790014e9d9510c4c034e9a1bb" title="permalink">#</a> </h3> <p> I used <a href="/2019/10/21/a-red-green-refactor-checklist">test-driven development</a> and <a href="https://fsharp.org">F#</a> for both unit tests and implementation. As usual, my test framework was <a href="https://xunit.net">xUnit.net</a> (2.4.0) with <a href="https://github.com/SwensenSoftware/unquote">Unquote</a> (5.0.0) as the assertion library. </p> <p> I could have done the exercise with a <a href="/property-based-testing-intro">property-based testing</a> framework like <a href="https://fscheck.github.io/FsCheck">FsCheck</a> or <a href="https://github.com/hedgehogqa/fsharp-hedgehog">Hedgehog</a>, but I chose instead to take my own medicine. In the kata description, I suggested some test cases, so I wanted to try and see if they made sense. </p> <p> The entire code base is <a href="https://github.com/ploeh/maitred-kata-in-fsharp-1">available on GitHub</a>. </p> <h3 id="adc8a50bbe72453c87853ae566b9a185"> Boutique restaurant <a href="#adc8a50bbe72453c87853ae566b9a185" title="permalink">#</a> </h3> <p> I wrote the first suggested test case this way: </p> <p> <pre>[&lt;Fact&gt;] <span style="color:blue;">let</span>&nbsp;``Boutique&nbsp;restaurant``&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;test&nbsp;&lt;@&nbsp;canAccept&nbsp;12&nbsp;[]&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;1&nbsp;}&nbsp;@&gt;</pre> </p> <p> This uses Unquote's <code>test</code> function to verify that a Boolean expression is true. The expression is a function call to <code>canAccept</code> with the capacity <code>12</code>, no existing reservations, and a reservation with <code>Quantity = 1</code>. </p> <p> The simplest thing that could possibly work was this: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;Reservation&nbsp;=&nbsp;{&nbsp;Quantity&nbsp;:&nbsp;int&nbsp;} <span style="color:blue;">let</span>&nbsp;canAccept&nbsp;_&nbsp;_&nbsp;_&nbsp;=&nbsp;<span style="color:blue;">true</span></pre> </p> <p> The <code>Reservation</code> type was required to make the test compile, but the <code>canAccept</code> function didn't have to consider its arguments. It could simply return <code>true</code>. </p> <h3 id="d169683993034e3c86db04a1dfaca279"> Parametrisation <a href="#d169683993034e3c86db04a1dfaca279" title="permalink">#</a> </h3> <p> The next test case made me turn the test function into a parametrised test: </p> <p> <pre>[&lt;Theory&gt;] [&lt;InlineData(&nbsp;1,&nbsp;&nbsp;<span style="color:blue;">true</span>)&gt;] [&lt;InlineData(13,&nbsp;<span style="color:blue;">false</span>)&gt;] <span style="color:blue;">let</span>&nbsp;``Boutique&nbsp;restaurant``&nbsp;quantity&nbsp;expected&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;canAccept&nbsp;12&nbsp;[]&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;quantity&nbsp;}</pre> </p> <p> So far, the only test parameters were <code>quantity</code> and the <code>expected</code> result. I could no longer use <code>test</code> to verify the result of calling <code>canAccept</code>, since I added variation to the <code>expected</code> result. I changed <code>test</code> into Unquote's <code>=!</code> (<em>must equal</em>) operator. </p> <p> The simplest passing implementation I could think of was: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;canAccept&nbsp;_&nbsp;_&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;q&nbsp;}&nbsp;=&nbsp;q&nbsp;=&nbsp;1</pre> </p> <p> It ignored the capacity and instead checked whether <code>q</code> is <code>1</code>. That passed both tests. </p> <h3 id="43fddd9f6ad845aa85b4f04357815659"> Test data API <a href="#43fddd9f6ad845aa85b4f04357815659" title="permalink">#</a> </h3> <p> Before adding another test case, I decided to refactor my test code a bit. When working with a real domain model, you often have to furnish test data in order to make code compile - even if that data isn't relevant to the test. I wanted to demonstrate how to deal with this issue. My first step was to introduce an 'arbitrary' <code>Reservation</code> value in the spirit of <a href="/2017/09/11/test-data-without-builders">Test data without Builders</a>. </p> <p> <pre><span style="color:blue;">let</span>&nbsp;aReservation&nbsp;=&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;1&nbsp;}</pre> </p> <p> This enabled me to rewrite the test: </p> <p> <pre>[&lt;Theory&gt;] [&lt;InlineData(&nbsp;1,&nbsp;&nbsp;<span style="color:blue;">true</span>)&gt;] [&lt;InlineData(13,&nbsp;<span style="color:blue;">false</span>)&gt;] <span style="color:blue;">let</span>&nbsp;``Boutique&nbsp;restaurant``&nbsp;quantity&nbsp;expected&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;canAccept&nbsp;12&nbsp;[]&nbsp;{&nbsp;aReservation&nbsp;<span style="color:blue;">with</span>&nbsp;Quantity&nbsp;=&nbsp;quantity&nbsp;}</pre> </p> <p> This doesn't look like an immediate improvement, but it made it possible to make the <code>Reservation</code> record type more realistic without damage to the test: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;Reservation&nbsp;=&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;:&nbsp;DateTime &nbsp;&nbsp;&nbsp;&nbsp;Name&nbsp;:&nbsp;string &nbsp;&nbsp;&nbsp;&nbsp;Email&nbsp;:&nbsp;string &nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;:&nbsp;int&nbsp;}</pre> </p> <p> I added some fields that a real-world reservation would have. The <code>Quantity</code> field will be useful later on, but the <code>Name</code> and <code>Email</code> fields are irrelevant in the context of the kata. </p> <p> This is the type of API change that often gives people grief. To create a <code>Reservation</code> value, you <em>must</em> supply all four fields. This often adds noise to tests. </p> <p> Not here, though, because the only concession I had to make was to change <code>aReservation</code>: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;aReservation&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;DateTime&nbsp;(2019,&nbsp;11,&nbsp;29,&nbsp;12,&nbsp;0,&nbsp;0) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Email&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;1 &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> The test code remained unaltered. </p> <p> With that in place, I could add the third test case: </p> <p> <pre>[&lt;Theory&gt;] [&lt;InlineData(&nbsp;1,&nbsp;&nbsp;<span style="color:blue;">true</span>)&gt;] [&lt;InlineData(13,&nbsp;<span style="color:blue;">false</span>)&gt;] [&lt;InlineData(12,&nbsp;&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;``Boutique&nbsp;restaurant``&nbsp;quantity&nbsp;expected&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;canAccept&nbsp;12&nbsp;[]&nbsp;{&nbsp;aReservation&nbsp;<span style="color:blue;">with</span>&nbsp;Quantity&nbsp;=&nbsp;quantity&nbsp;}</pre> </p> <p> The simplest passing implementation I could think of was: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;canAccept&nbsp;_&nbsp;_&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;q&nbsp;}&nbsp;=&nbsp;q&nbsp;&lt;&gt;&nbsp;13</pre> </p> <p> This implementation still ignored the restaurant's capacity and simply checked that <code>q</code> was different from <code>13</code>. That was enough to pass all three tests. </p> <h3 id="b25e3ea455db4fc6a0a18ed84d3be679"> Refactor test case code <a href="#b25e3ea455db4fc6a0a18ed84d3be679" title="permalink">#</a> </h3> <p> Adding the next suggested test case proved to be a problem. I wanted to write a single <code>[&lt;Theory&gt;]</code>-driven test function fed by all the <em>Boutique restaurant</em> test data. To do that, I'd have to supply arrays of test input, but unfortunately, <a href="https://github.com/dotnet/fsharp/issues/7916">that wasn't possible in F#</a>. </p> <p> Instead I decided to refactor the test case code to use <code>ClassData</code>-driven test cases. </p> <p> <pre><span style="color:blue;">type</span>&nbsp;BoutiqueTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;int,&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;(&nbsp;1,&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(13,&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;<span style="color:blue;">true</span>) [&lt;Theory;&nbsp;ClassData(typeof&lt;BoutiqueTestCases&gt;)&gt;] <span style="color:blue;">let</span>&nbsp;``Boutique&nbsp;restaurant``&nbsp;quantity&nbsp;expected&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;canAccept&nbsp;12&nbsp;[]&nbsp;{&nbsp;aReservation&nbsp;<span style="color:blue;">with</span>&nbsp;Quantity&nbsp;=&nbsp;quantity&nbsp;}</pre> </p> <p> These are the same test cases as before, but now expressed by a class inheriting from <code>TheoryData&lt;int, bool&gt;</code>. The implementing code remains the same. </p> <h3 id="d1c356e19bd940cd8e37c24848b4f896"> Existing reservation <a href="#d1c356e19bd940cd8e37c24848b4f896" title="permalink">#</a> </h3> <p> The next suggested test case includes an existing reservation. To support that, I changed the test case base class to <code>TheoryData&lt;int, int list, int, bool&gt;</code>, and passed empty lists for the first three test cases. For the new, fourth test case, I supplied a number of seats. </p> <p> <pre><span style="color:blue;">type</span>&nbsp;BoutiqueTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;int,&nbsp;int&nbsp;list,&nbsp;int,&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;[],&nbsp;&nbsp;1,&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;[],&nbsp;13,&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;[],&nbsp;12,&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(&nbsp;4,&nbsp;[2],&nbsp;&nbsp;3,&nbsp;<span style="color:blue;">false</span>) [&lt;Theory;&nbsp;ClassData(typeof&lt;BoutiqueTestCases&gt;)&gt;] <span style="color:blue;">let</span>&nbsp;``Boutique&nbsp;restaurant``&nbsp;capacity&nbsp;reservatedSeats&nbsp;quantity&nbsp;expected&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;rs&nbsp;=&nbsp;List.map&nbsp;(<span style="color:blue;">fun</span>&nbsp;s&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;{&nbsp;aReservation&nbsp;<span style="color:blue;">with</span>&nbsp;Quantity&nbsp;=&nbsp;s&nbsp;})&nbsp;reservatedSeats &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;canAccept&nbsp;capacity&nbsp;rs&nbsp;{&nbsp;aReservation&nbsp;<span style="color:blue;">with</span>&nbsp;Quantity&nbsp;=&nbsp;quantity&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;actual</pre> </p> <p> This also forced me to to change the body of the test function. At this stage, it could be prettier, but it got the job done. I soon after improved it. </p> <p> My implementation, as usual, was <em>the simplest thing that could possibly work</em>. </p> <p> <pre><span style="color:blue;">let</span>&nbsp;canAccept&nbsp;_&nbsp;reservations&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;q&nbsp;}&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;q&nbsp;&lt;&gt;&nbsp;13&nbsp;&amp;&amp;&nbsp;Seq.isEmpty&nbsp;reservations</pre> </p> <p> Notice that although the fourth test case varied the <code>capacity</code>, I still managed to pass all tests without looking at it. </p> <h3 id="b08aade19008419cab173c9ab720cfca"> Accept despite existing reservation <a href="#b08aade19008419cab173c9ab720cfca" title="permalink">#</a> </h3> <p> The next test case introduced another existing reservation, but this time with enough capacity to accept a new reservation. </p> <p> <pre><span style="color:blue;">type</span>&nbsp;BoutiqueTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;int,&nbsp;int&nbsp;list,&nbsp;int,&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;[],&nbsp;&nbsp;1,&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;[],&nbsp;13,&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;[],&nbsp;12,&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(&nbsp;4,&nbsp;[2],&nbsp;&nbsp;3,&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(10,&nbsp;[2],&nbsp;&nbsp;3,&nbsp;&nbsp;<span style="color:blue;">true</span>)</pre> </p> <p> The test function remained unchanged. </p> <p> In the spirit of the <a href="/2019/10/07/devils-advocate">Devil's advocate technique</a>, I actively sought to avoid a correct implementation. I came up with this: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;canAccept&nbsp;capacity&nbsp;reservations&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;q&nbsp;}&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;Seq.tryHead&nbsp;reservations&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;None&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;0 &nbsp;&nbsp;&nbsp;&nbsp;reservedSeats&nbsp;+&nbsp;q&nbsp;&lt;=&nbsp;capacity</pre> </p> <p> Since all test cases supplied at most one existing reservation, it was enough to consider the first reservation, if present. </p> <p> To many people, it may seem strange to actively seek out incorrect implementations like this. An incorrect implementation that passes all tests does, however, demonstrate the need for more tests. </p> <h3 id="587afbd29a9d41879994d2663c26f8bb"> The sum of all reservations <a href="#587afbd29a9d41879994d2663c26f8bb" title="permalink">#</a> </h3> <p> I then added another test case, this time with three existing reservations: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;BoutiqueTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;int,&nbsp;int&nbsp;list,&nbsp;int,&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[],&nbsp;&nbsp;1,&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[],&nbsp;13,&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[],&nbsp;12,&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(&nbsp;4,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[2],&nbsp;&nbsp;3,&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(10,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[2],&nbsp;&nbsp;3,&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(10,&nbsp;[3;2;3],&nbsp;&nbsp;3,&nbsp;<span style="color:blue;">false</span>)</pre> </p> <p> Again, I left the test function untouched. </p> <p> On the side of the implementation, I couldn't think of more hoops to jump through, so I finally gave in and provided a 'proper' implementation: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;canAccept&nbsp;capacity&nbsp;reservations&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;q&nbsp;}&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;=&nbsp;Seq.sumBy&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity)&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;reservedSeats&nbsp;+&nbsp;q&nbsp;&lt;=&nbsp;capacity</pre> </p> <p> Not only does it look simpler that before, but I also felt that the implementation was warranted. <blockquote> <p> “As the tests get more specific, the code gets more generic.” </p> <footer><cite><a href="https://blog.cleancoder.com/uncle-bob/2013/05/27/TheTransformationPriorityPremise.html">Robert C. Martin</a></cite></footer> </blockquote> Although I'd only tested <code>canAccept</code> with lists, I decided to implement it with <code>Seq</code>. This was a decision I later regretted. </p> <h3 id="987a4fc4119a4ab29bc968712659bdc2"> Another date <a href="#987a4fc4119a4ab29bc968712659bdc2" title="permalink">#</a> </h3> <p> The last <em>Boutique restaurant</em> test case was to supply an existing reservation on another date. The <code>canAccept</code> function should only consider existing reservations on the date in question. </p> <p> First, I decided to model the two separate dates as two values: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;d1&nbsp;=&nbsp;DateTime&nbsp;(2023,&nbsp;9,&nbsp;14) <span style="color:blue;">let</span>&nbsp;d2&nbsp;=&nbsp;DateTime&nbsp;(2023,&nbsp;9,&nbsp;15)</pre> </p> <p> I hoped that it would make my test cases more readable, because the dates would have a denser representation. </p> <p> <pre><span style="color:blue;">type</span>&nbsp;BoutiqueTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;int,&nbsp;(int&nbsp;*&nbsp;DateTime)&nbsp;list,&nbsp;(int&nbsp;*&nbsp;DateTime),&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[],&nbsp;(&nbsp;1,&nbsp;d1),&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[],&nbsp;(13,&nbsp;d1),&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[],&nbsp;(12,&nbsp;d1),&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(&nbsp;4,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[(2,&nbsp;d1)],&nbsp;(&nbsp;3,&nbsp;d1),&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(10,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[(2,&nbsp;d1)],&nbsp;(&nbsp;3,&nbsp;d1),&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(10,&nbsp;[(3,&nbsp;d1);(2,&nbsp;d1);(3,&nbsp;d1)],&nbsp;(&nbsp;3,&nbsp;d1),&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(&nbsp;4,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[(2,&nbsp;d2)],&nbsp;(&nbsp;3,&nbsp;d1),&nbsp;&nbsp;<span style="color:blue;">true</span>)</pre> </p> <p> I changed the representation of a reservation from just an <code>int</code> to a tuple of a number and a date. I also got tired of looking at that noisy unit test, so I introduced a test-specific helper function: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;reserve&nbsp;(q,&nbsp;d)&nbsp;=&nbsp;{&nbsp;aReservation&nbsp;<span style="color:blue;">with</span>&nbsp;Quantity&nbsp;=&nbsp;q;&nbsp;Date&nbsp;=&nbsp;d&nbsp;}</pre> </p> <p> Since it takes a tuple of a number and a date, I could use it to simplify the test function: </p> <p> <pre>[&lt;Theory;&nbsp;ClassData(typeof&lt;BoutiqueTestCases&gt;)&gt;] <span style="color:blue;">let</span>&nbsp;``Boutique&nbsp;restaurant``&nbsp;(capacity,&nbsp;rs,&nbsp;r,&nbsp;expected)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservations&nbsp;=&nbsp;List.map&nbsp;reserve&nbsp;rs &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;canAccept&nbsp;capacity&nbsp;reservations&nbsp;(reserve&nbsp;r) &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;actual</pre> </p> <p> The <code>canAccept</code> function now had to filter the <code>reservations</code> on <code>Date</code>: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;canAccept&nbsp;capacity&nbsp;reservations&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;q;&nbsp;Date&nbsp;=&nbsp;d&nbsp;}&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;relevantReservations&nbsp;=&nbsp;Seq.filter&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Date&nbsp;=&nbsp;d)&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;=&nbsp;Seq.sumBy&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity)&nbsp;relevantReservations &nbsp;&nbsp;&nbsp;&nbsp;reservedSeats&nbsp;+&nbsp;q&nbsp;&lt;=&nbsp;capacity</pre> </p> <p> This implementation specifically compared dates, though, so while it passed all tests, it'd behave incorrectly if the dates were as much as nanosecond off. That implied that another test case was required. </p> <h3 id="535fc318a9b74ffda89e4e02992efe41"> Same date, different time <a href="#535fc318a9b74ffda89e4e02992efe41" title="permalink">#</a> </h3> <p> The final test case for the <em>Boutique restaurant</em>, then, was to use two <code>DateTime</code> values on the same date, but with different times. </p> <p> <pre><span style="color:blue;">type</span>&nbsp;BoutiqueTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;int,&nbsp;(int&nbsp;*&nbsp;DateTime)&nbsp;list,&nbsp;(int&nbsp;*&nbsp;DateTime),&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[],&nbsp;(&nbsp;1,&nbsp;d1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;),&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[],&nbsp;(13,&nbsp;d1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;),&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(12,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[],&nbsp;(12,&nbsp;d1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;),&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(&nbsp;4,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[(2,&nbsp;d1)],&nbsp;(&nbsp;3,&nbsp;d1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;),&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(10,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[(2,&nbsp;d1)],&nbsp;(&nbsp;3,&nbsp;d1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;),&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(10,&nbsp;[(3,&nbsp;d1);(2,&nbsp;d1);(3,&nbsp;d1)],&nbsp;(&nbsp;3,&nbsp;d1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;),&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(&nbsp;4,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[(2,&nbsp;d2)],&nbsp;(&nbsp;3,&nbsp;d1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;),&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(&nbsp;4,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[(2,&nbsp;d1)],&nbsp;(&nbsp;3,&nbsp;d1.AddHours&nbsp;1.),&nbsp;<span style="color:blue;">false</span>)</pre> </p> <p> I just added a new test case as a new line and lined up the data. The test function, again, didn't change. </p> <p> To address the new test case, I generalised the first filter. </p> <p> <pre><span style="color:blue;">let</span>&nbsp;canAccept&nbsp;capacity&nbsp;reservations&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;q;&nbsp;Date&nbsp;=&nbsp;d&nbsp;}&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;relevantReservations&nbsp;=&nbsp;Seq.filter&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Date.Date&nbsp;=&nbsp;d.Date)&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;=&nbsp;Seq.sumBy&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity)&nbsp;relevantReservations &nbsp;&nbsp;&nbsp;&nbsp;reservedSeats&nbsp;+&nbsp;q&nbsp;&lt;=&nbsp;capacity</pre> </p> <p> An expression like <code>r.Date.Date</code> looks a little odd. <code>DateTime</code> values have a <code>Date</code> property that represents its date part. The first <code>Date</code> is the <code>Reservation</code> field, and the second is the date part. </p> <p> I was now content with the <em>Boutique restaurant</em> implementation. </p> <h3 id="ea07bcad3ac8429194c55edddb7187d7"> Haute cuisine <a href="#ea07bcad3ac8429194c55edddb7187d7" title="permalink">#</a> </h3> <p> In the next phase of the kata, I now had to deal with a configuration of more than one table, so I introduced a type: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;Table&nbsp;=&nbsp;{&nbsp;Seats&nbsp;:&nbsp;int&nbsp;}</pre> </p> <p> It's really only a glorified wrapper around an <code>int</code>, but with a real domain model in place, I could make its constructor private and instead afford a smart constructor that only accepts positive integers. </p> <p> I changed the <code>canAccept</code> function to take a list of tables, instead of <code>capacity</code>. This also required me to change the existing test function to take a singleton list of tables: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;canAccept&nbsp;[table&nbsp;capacity]&nbsp;reservations&nbsp;(reserve&nbsp;r)</pre> </p> <p> where <code>table</code> is a test-specific helper function: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;table&nbsp;s&nbsp;=&nbsp;{&nbsp;Seats&nbsp;=&nbsp;s&nbsp;}</pre> </p> <p> I also added a new test function and a single test case: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;d3&nbsp;=&nbsp;DateTime&nbsp;(2024,&nbsp;6,&nbsp;&nbsp;7) <span style="color:blue;">type</span>&nbsp;HauteCuisineTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;int&nbsp;list,&nbsp;(int&nbsp;*&nbsp;DateTime)&nbsp;list,&nbsp;(int&nbsp;*&nbsp;DateTime),&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;([2;2;4;4],&nbsp;[],&nbsp;(4,&nbsp;d3),&nbsp;<span style="color:blue;">true</span>) [&lt;Theory;&nbsp;ClassData(typeof&lt;HauteCuisineTestCases&gt;)&gt;] <span style="color:blue;">let</span>&nbsp;``Haute&nbsp;cuisine``&nbsp;(tableSeats,&nbsp;rs,&nbsp;r,&nbsp;expected)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;tables&nbsp;=&nbsp;List.map&nbsp;table&nbsp;tableSeats &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservations&nbsp;=&nbsp;List.map&nbsp;reserve&nbsp;rs &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;canAccept&nbsp;tables&nbsp;reservations&nbsp;(reserve&nbsp;r) &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;actual</pre> </p> <p> The change to <code>canAccept</code> is modest: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;canAccept&nbsp;tables&nbsp;reservations&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;q;&nbsp;Date&nbsp;=&nbsp;d&nbsp;}&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;capacity&nbsp;=&nbsp;Seq.sumBy&nbsp;(<span style="color:blue;">fun</span>&nbsp;t&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;t.Seats)&nbsp;tables &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;relevantReservations&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.filter&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Date.Date&nbsp;=&nbsp;d.Date)&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;=&nbsp;Seq.sumBy&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity)&nbsp;relevantReservations &nbsp;&nbsp;&nbsp;&nbsp;reservedSeats&nbsp;+&nbsp;q&nbsp;&lt;=&nbsp;capacity</pre> </p> <p> It still works by looking at a total capacity as if there was just a single communal table. Now it just calculates <code>capacity</code> from the sequence of <code>tables</code>. </p> <h3 id="334eab19b5864f72a92290cfe5031b66"> Reject reservation that doesn't fit largest table <a href="#334eab19b5864f72a92290cfe5031b66" title="permalink">#</a> </h3> <p> Then I added the next test case to the new test function: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;HauteCuisineTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;int&nbsp;list,&nbsp;(int&nbsp;*&nbsp;DateTime)&nbsp;list,&nbsp;(int&nbsp;*&nbsp;DateTime),&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;([2;2;4;4],&nbsp;[],&nbsp;(4,&nbsp;d3),&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;([2;2;4;4],&nbsp;[],&nbsp;(5,&nbsp;d3),&nbsp;<span style="color:blue;">false</span>)</pre> </p> <p> This one attempts to make a reservation for five people. The largest table only fits four people, so this reservation should be rejected. The current implementation just considered the total capacity of all tables, to it accepted the reservation, and thereby failed the test. </p> <p> This change to <code>canAccept</code> passes all tests: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;canAccept&nbsp;tables&nbsp;reservations&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;q;&nbsp;Date&nbsp;=&nbsp;d&nbsp;}&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;capacity&nbsp;=&nbsp;tables&nbsp;|&gt;&nbsp;Seq.map&nbsp;(<span style="color:blue;">fun</span>&nbsp;t&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;t.Seats)&nbsp;|&gt;&nbsp;Seq.max &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;relevantReservations&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.filter&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Date.Date&nbsp;=&nbsp;d.Date)&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;=&nbsp;Seq.sumBy&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity)&nbsp;relevantReservations &nbsp;&nbsp;&nbsp;&nbsp;reservedSeats&nbsp;+&nbsp;q&nbsp;&lt;=&nbsp;capacity</pre> </p> <p> The function now only considered the largest table in the restaurant. While it's incorrect to ignore all other tables, all tests passed. </p> <h3 id="54e03a3eeb744db3bc82b75aace9556f"> Accept when there's still a remaining table <a href="#54e03a3eeb744db3bc82b75aace9556f" title="permalink">#</a> </h3> <p> Only considering the largest table is obviously wrong, so I added another test case where there's an existing reservation. </p> <p> <pre><span style="color:blue;">type</span>&nbsp;HauteCuisineTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;int&nbsp;list,&nbsp;(int&nbsp;*&nbsp;DateTime)&nbsp;list,&nbsp;(int&nbsp;*&nbsp;DateTime),&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;([2;2;4;4],&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[],&nbsp;(4,&nbsp;d3),&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;([2;2;4;4],&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[],&nbsp;(5,&nbsp;d3),&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(&nbsp;&nbsp;[2;2;4],&nbsp;[(2,&nbsp;d3)],&nbsp;(4,&nbsp;d3),&nbsp;&nbsp;<span style="color:blue;">true</span>)</pre> </p> <p> While <code>canAccept</code> should accept the reservation, it didn't when I added the test case. In a variation of the <a href="/2019/10/07/devils-advocate">Devil's Advocate</a> technique, I came up with this implementation to pass all tests: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;canAccept&nbsp;tables&nbsp;reservations&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;q;&nbsp;Date&nbsp;=&nbsp;d&nbsp;}&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;largestTable&nbsp;=&nbsp;tables&nbsp;|&gt;&nbsp;Seq.map&nbsp;(<span style="color:blue;">fun</span>&nbsp;t&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;t.Seats)&nbsp;|&gt;&nbsp;Seq.max &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;capacity&nbsp;=&nbsp;tables&nbsp;|&gt;&nbsp;Seq.sumBy&nbsp;(<span style="color:blue;">fun</span>&nbsp;t&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;t.Seats) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;relevantReservations&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.filter&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Date.Date&nbsp;=&nbsp;d.Date)&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;=&nbsp;Seq.sumBy&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity)&nbsp;relevantReservations &nbsp;&nbsp;&nbsp;&nbsp;q&nbsp;&lt;=&nbsp;largestTable&nbsp;&amp;&amp;&nbsp;reservedSeats&nbsp;+&nbsp;q&nbsp;&lt;=&nbsp;capacity</pre> </p> <p> This still wasn't the correct implementation. It represented a return to looking at the total capacity of all tables, with the extra rule that you couldn't make a reservation larger than the largest table. At least one more test case was needed. </p> <h3 id="d900c55b4ebc4bcbba572cd8cbca33ed"> Accept when remaining table is available <a href="#d900c55b4ebc4bcbba572cd8cbca33ed" title="permalink">#</a> </h3> <p> I added another test case to the <em>haute cuisine</em> test cases. This one came with one existing reservation for three people, effectively reserving the four-person table. While the remaining tables have an aggregate capacity of four, it's two separate tables. Therefore, a reservation for four people should be rejected. </p> <p> <pre><span style="color:blue;">type</span>&nbsp;HauteCuisineTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;int&nbsp;list,&nbsp;(int&nbsp;*&nbsp;DateTime)&nbsp;list,&nbsp;(int&nbsp;*&nbsp;DateTime),&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;([2;2;4;4],&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[],&nbsp;(4,&nbsp;d3),&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;([2;2;4;4],&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[],&nbsp;(5,&nbsp;d3),&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(&nbsp;&nbsp;[2;2;4],&nbsp;[(2,&nbsp;d3)],&nbsp;(4,&nbsp;d3),&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;(&nbsp;&nbsp;[2;2;4],&nbsp;[(3,&nbsp;d3)],&nbsp;(4,&nbsp;d3),&nbsp;<span style="color:blue;">false</span>)</pre> </p> <p> It then dawned on me that I had to explicitly distinguish between a communal table configuration, and individual tables that aren't communal, regardless of size. This triggered quite a refactoring. </p> <p> I defined a new type to distinguish between these two types of table layout: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;TableConfiguration&nbsp;=&nbsp;Communal&nbsp;<span style="color:blue;">of</span>&nbsp;int&nbsp;|&nbsp;Tables&nbsp;<span style="color:blue;">of</span>&nbsp;Table&nbsp;list</pre> </p> <p> I also had to change the existing test functions, including the <em>boutique restaurant</em> test </p> <p> <pre>[&lt;Theory;&nbsp;ClassData(typeof&lt;BoutiqueTestCases&gt;)&gt;] <span style="color:blue;">let</span>&nbsp;``Boutique&nbsp;restaurant``&nbsp;(capacity,&nbsp;rs,&nbsp;r,&nbsp;expected)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservations&nbsp;=&nbsp;List.map&nbsp;reserve&nbsp;rs &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;canAccept&nbsp;(Communal&nbsp;capacity)&nbsp;reservations&nbsp;(reserve&nbsp;r) &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;actual</pre></pre> </p> <p> and the <em>haute cuisine</em> test </p> <p> <pre>[&lt;Theory;&nbsp;ClassData(typeof&lt;HauteCuisineTestCases&gt;)&gt;] <span style="color:blue;">let</span>&nbsp;``Haute&nbsp;cuisine``&nbsp;(tableSeats,&nbsp;rs,&nbsp;r,&nbsp;expected)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;tables&nbsp;=&nbsp;List.map&nbsp;table&nbsp;tableSeats &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservations&nbsp;=&nbsp;List.map&nbsp;reserve&nbsp;rs &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;canAccept&nbsp;(Tables&nbsp;tables)&nbsp;reservations&nbsp;(reserve&nbsp;r) &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;actual</pre> </p> <p> In both cases I had to change the call to <code>canAccept</code> to pass either a <code>Communal</code> or a <code>Tables</code> value. </p> <h3 id="c3c6acc07a0f4e129fc7159247a7058a"> Delete first <a href="#c3c6acc07a0f4e129fc7159247a7058a" title="permalink">#</a> </h3> <p> I'd previously done the kata in <a href="https://www.haskell.org">Haskell</a> and was able to solve this phase of the kata using the built-in <code>deleteFirstsBy</code> function. This function doesn't exist in the F# core library, so I decided to add it. I created a new module named <code>Seq</code> and first defined a function that deletes the first element that satisfies a predicate: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;bool)&nbsp;-&gt;&nbsp;seq&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;seq&lt;&#39;a&gt;</span> <span style="color:blue;">let</span>&nbsp;deleteFirstBy&nbsp;pred&nbsp;(xs&nbsp;:&nbsp;_&nbsp;seq)&nbsp;=&nbsp;seq&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:blue;">mutable</span>&nbsp;found&nbsp;=&nbsp;<span style="color:blue;">false</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">use</span>&nbsp;e&nbsp;=&nbsp;xs.GetEnumerator&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">while</span>&nbsp;e.MoveNext&nbsp;()&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;found &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:blue;">yield</span>&nbsp;e.Current &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:blue;">if</span>&nbsp;pred&nbsp;e.Current &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;found&nbsp;<span style="color:blue;">&lt;-</span>&nbsp;<span style="color:blue;">true</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:blue;">yield</span>&nbsp;e.Current &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> It moves over a sequence of elements and looks for an element that satisfies <code>pred</code>. If such an element is found, it's omitted from the output sequence. The function only deletes the first occurrence from the sequence, so any other elements that satisfy the predicate are still included. </p> <p> This function corresponds to Haskell's <code>deleteBy</code> function and can be used to implement <code>deleteFirstsBy</code>: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b&nbsp;-&gt;&nbsp;bool)&nbsp;-&gt;&nbsp;seq&lt;&#39;b&gt;&nbsp;-&gt;&nbsp;seq&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;seq&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;deleteFirstsBy&nbsp;pred&nbsp;=&nbsp;Seq.fold&nbsp;(<span style="color:blue;">fun</span>&nbsp;xs&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;deleteFirstBy&nbsp;(pred&nbsp;x)&nbsp;xs)</pre> </p> <p> As <a href="https://hackage.haskell.org/package/base/docs/Data-List.html#v:deleteFirstsBy">the Haskell documentation</a> explains, the "<code>deleteFirstsBy</code> function takes a predicate and two lists and returns the first list with the first occurrence of each element of the second list removed." My F# function does the same, but works on sequences instead of linked lists. </p> <p> I could use it to find and remove tables that were already reserved. </p> <h3 id="f2c9fa5bfc6642378cf0d8edb2a637d5"> Find remaining tables <a href="#f2c9fa5bfc6642378cf0d8edb2a637d5" title="permalink">#</a> </h3> <p> I first defined a little helper function to determine whether a table can accommodate a reservation: </p> <p> <pre><span style="color:green;">//&nbsp;Reservation&nbsp;-&gt;&nbsp;Table&nbsp;-&gt;&nbsp;bool</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;fits&nbsp;r&nbsp;t&nbsp;=&nbsp;r.Quantity&nbsp;&lt;=&nbsp;t.Seats</pre> </p> <p> The rule is simply that the table's number of <code>Seats</code> must be greater than or equal to the reservation's <code>Quantity</code>. I could use this function for the predicate for <code>Seq.deleteFirstsBy</code>: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;canAccept&nbsp;config&nbsp;reservations&nbsp;({&nbsp;Quantity&nbsp;=&nbsp;q;&nbsp;Date&nbsp;=&nbsp;d&nbsp;}&nbsp;<span style="color:blue;">as</span>&nbsp;r)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;contemporaneousReservations&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.filter&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Date.Date&nbsp;=&nbsp;d.Date)&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;config&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Communal&nbsp;capacity&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.sumBy&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity)&nbsp;contemporaneousReservations &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservedSeats&nbsp;+&nbsp;q&nbsp;&lt;=&nbsp;capacity &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Tables&nbsp;tables&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;rs&nbsp;=&nbsp;Seq.sort&nbsp;contemporaneousReservations &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;remainingTables&nbsp;=&nbsp;Seq.deleteFirstsBy&nbsp;fits&nbsp;(Seq.sort&nbsp;tables)&nbsp;rs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.exists&nbsp;(fits&nbsp;r)&nbsp;remainingTables</pre> </p> <p> The <code>canAccept</code> function now branched on <code>Communal</code> versus <code>Tables</code> configurations. In the <code>Communal</code> configuration, it simply compared the <code>reservedSeats</code> and reservation quantity to the communal table's <code>capacity</code>. </p> <p> In the <code>Tables</code> case, the function used <code>Seq.deleteFirstsBy fits</code> to remove all the tables that are already reserved. The result is the <code>remainingTables</code>. If there exists a remaining table that <code>fits</code> the reservation, then the function accepts the reservation. </p> <p> This seemed to me an appropriate implementation of the <em>haute cuisine</em> phase of the kata. </p> <h3 id="5a4a8061a2324ceab96e22a10a5ff445"> Second seatings <a href="#5a4a8061a2324ceab96e22a10a5ff445" title="permalink">#</a> </h3> <p> Now it was time to take seating duration into account. While I could have written my test cases directly against the <a href="https://docs.microsoft.com/dotnet/api/system.timespan">TimeSpan API</a>, I didn't want to write <code>TimeSpan.FromHours 2.5</code>, <code>TimeSpan.FromDays 1.</code>, and so on. I found that it made my test cases harder to read, so I added some literal extensions: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;Int32&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;x.hours&nbsp;=&nbsp;TimeSpan.FromHours&nbsp;(float&nbsp;x) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;x.days&nbsp;=&nbsp;TimeSpan.FromDays&nbsp;(float&nbsp;x)</pre> </p> <p> This enabled me to write expressions like <code>1 .days</code> and <code>2 .hours</code>, as shown in the first test case: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;d4&nbsp;=&nbsp;DateTime&nbsp;(2023,&nbsp;10,&nbsp;22,&nbsp;18,&nbsp;0,&nbsp;0) <span style="color:blue;">type</span>&nbsp;SecondSeatingsTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;TimeSpan,&nbsp;int&nbsp;list,&nbsp;(int&nbsp;*&nbsp;DateTime)&nbsp;list,&nbsp;(int&nbsp;*&nbsp;DateTime),&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;(2&nbsp;.hours,&nbsp;[2;2;4],&nbsp;[(4,&nbsp;d4)],&nbsp;(3,&nbsp;d4.Add&nbsp;(2&nbsp;.hours)),&nbsp;<span style="color:blue;">true</span>)</pre> </p> <p> I used this initial parametrised test case for a new test function: </p> <p> <pre>[&lt;Theory;&nbsp;ClassData(typeof&lt;SecondSeatingsTestCases&gt;)&gt;] <span style="color:blue;">let</span>&nbsp;``Second&nbsp;seatings``&nbsp;(dur,&nbsp;tableSeats,&nbsp;rs,&nbsp;r,&nbsp;expected)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;tables&nbsp;=&nbsp;List.map&nbsp;table&nbsp;tableSeats &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservations&nbsp;=&nbsp;List.map&nbsp;reserve&nbsp;rs &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;canAccept&nbsp;dur&nbsp;(Tables&nbsp;tables)&nbsp;reservations&nbsp;(reserve&nbsp;r) &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;actual</pre> </p> <p> My motivation for this test case was mostly to introduce an API change to <code>canAccept</code>. I didn't want to rock the boat too much, so I picked a test case that wouldn't trigger a big change to the implementation. I prefer incremental changes. The only change is the introduction of the <code>seatingDur</code> argument: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;canAccept&nbsp;(seatingDur&nbsp;:&nbsp;TimeSpan)&nbsp;config&nbsp;reservations&nbsp;({&nbsp;Date&nbsp;=&nbsp;d&nbsp;}&nbsp;<span style="color:blue;">as</span>&nbsp;r)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;contemporaneousReservations&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.filter&nbsp;(<span style="color:blue;">fun</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x.Date.Subtract&nbsp;seatingDur&nbsp;&lt;&nbsp;d.Date)&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;config&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Communal&nbsp;capacity&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.sumBy&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity)&nbsp;contemporaneousReservations &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservedSeats&nbsp;+&nbsp;r.Quantity&nbsp;&lt;=&nbsp;capacity &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Tables&nbsp;tables&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;rs&nbsp;=&nbsp;Seq.sort&nbsp;contemporaneousReservations &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;remainingTables&nbsp;=&nbsp;Seq.deleteFirstsBy&nbsp;fits&nbsp;(Seq.sort&nbsp;tables)&nbsp;rs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.exists&nbsp;(fits&nbsp;r)&nbsp;remainingTables</pre> </p> <p> While the function already considered <code>seatingDur</code>, the way it filtered <code>reservation</code> wasn't entirely correct. It passed all tests, though. </p> <h3 id="2411805a41764ba3b166612ffa392246"> Filter reservations based on seating duration <a href="#2411805a41764ba3b166612ffa392246" title="permalink">#</a> </h3> <p> The next test case I added made me write what I consider the right implementation, but I subsequently decided to add two more test cases just for confidence. Here's all of them: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;SecondSeatingsTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;TimeSpan,&nbsp;int&nbsp;list,&nbsp;(int&nbsp;*&nbsp;DateTime)&nbsp;list,&nbsp;(int&nbsp;*&nbsp;DateTime),&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2&nbsp;.hours, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[2;2;4], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[(4,&nbsp;d4)], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(3,&nbsp;d4.Add&nbsp;(2&nbsp;.hours)), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.5&nbsp;.hours, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[2;4;4], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[(2,&nbsp;d4);(1,&nbsp;d4.AddMinutes&nbsp;15.);(2,&nbsp;d4.Subtract&nbsp;(15&nbsp;.minutes))], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(3,&nbsp;d4.AddHours&nbsp;2.), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.5&nbsp;.hours, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[2;4;4], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[(2,&nbsp;d4);(2,&nbsp;d4.Subtract&nbsp;(15&nbsp;.minutes))], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(3,&nbsp;d4.AddHours&nbsp;2.), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.5&nbsp;.hours, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[2;4;4], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[(2,&nbsp;d4);(1,&nbsp;d4.AddMinutes&nbsp;15.);(2,&nbsp;d4.Subtract&nbsp;(15&nbsp;.minutes))], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(3,&nbsp;d4.AddHours&nbsp;2.25), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">true</span>)</pre> </p> <p> The new test cases use some more literal extensions: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;Int32&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;x.minutes&nbsp;=&nbsp;TimeSpan.FromMinutes&nbsp;(float&nbsp;x) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;x.hours&nbsp;=&nbsp;TimeSpan.FromHours&nbsp;(float&nbsp;x) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;x.days&nbsp;=&nbsp;TimeSpan.FromDays&nbsp;(float&nbsp;x) <span style="color:blue;">type</span>&nbsp;Double&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;x.hours&nbsp;=&nbsp;TimeSpan.FromHours&nbsp;x</pre> </p> <p> I added a private <code>isContemporaneous</code> function to the code base and used it to filter the reservation to pass the tests: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;isContemporaneous &nbsp;&nbsp;&nbsp;&nbsp;(seatingDur&nbsp;:&nbsp;TimeSpan) &nbsp;&nbsp;&nbsp;&nbsp;(candidate&nbsp;:&nbsp;Reservation) &nbsp;&nbsp;&nbsp;&nbsp;(existing&nbsp;:&nbsp;Reservation)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;aSeatingBefore&nbsp;=&nbsp;candidate.Date.Subtract&nbsp;seatingDur &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;aSeatingAfter&nbsp;=&nbsp;candidate.Date.Add&nbsp;seatingDur &nbsp;&nbsp;&nbsp;&nbsp;aSeatingBefore&nbsp;&lt;&nbsp;existing.Date&nbsp;&amp;&amp;&nbsp;existing.Date&nbsp;&lt;&nbsp;aSeatingAfter <span style="color:blue;">let</span>&nbsp;canAccept&nbsp;(seatingDur&nbsp;:&nbsp;TimeSpan)&nbsp;config&nbsp;reservations&nbsp;r&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;contemporaneousReservations&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.filter&nbsp;(isContemporaneous&nbsp;seatingDur&nbsp;r)&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;config&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Communal&nbsp;capacity&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.sumBy&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity)&nbsp;contemporaneousReservations &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservedSeats&nbsp;+&nbsp;r.Quantity&nbsp;&lt;=&nbsp;capacity &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Tables&nbsp;tables&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;rs&nbsp;=&nbsp;Seq.sort&nbsp;contemporaneousReservations &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;remainingTables&nbsp;=&nbsp;Seq.deleteFirstsBy&nbsp;fits&nbsp;(Seq.sort&nbsp;tables)&nbsp;rs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.exists&nbsp;(fits&nbsp;r)&nbsp;remainingTables</pre> </p> <p> I could have left the functionality of <code>isContemporaneous</code> inside of <code>canAccept</code>, but I found it just hard enough to get my head around that I preferred to put it in a named helper function. Checking that a value is in a range is in itself trivial, but for some reason, figuring out the limits of the range didn't come naturally to me. </p> <p> This version of <code>canAccept</code> only considered existing reservations if they in any way overlapped with the reservation in question. It passed all tests. It also seemed to me to be a satisfactory implementation of the <em>second seatings</em> scenario. </p> <h3 id="7b7ede53fafc4a25b6bbb3fe9bbb4f09"> Alternative table configurations <a href="#7b7ede53fafc4a25b6bbb3fe9bbb4f09" title="permalink">#</a> </h3> <p> This state of the kata introduces groups of tables that can be reserved individually, or combined. To support that, I changed the definition of <code>Table</code>: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;Table&nbsp;=&nbsp;Discrete&nbsp;<span style="color:blue;">of</span>&nbsp;int&nbsp;|&nbsp;Group&nbsp;<span style="color:blue;">of</span>&nbsp;int&nbsp;list</pre> </p> <p> A <code>Table</code> is now either a <code>Discrete</code> table that can't be combined, or a <code>Group</code> of tables that can either be reserved individually, or combined. </p> <p> I had to change the test-specific <code>table</code> function to behave like before. </p> <p> <pre><span style="color:blue;">let</span>&nbsp;table&nbsp;s&nbsp;=&nbsp;Discrete&nbsp;s</pre> </p> <p> Before this change to the <code>Table</code> type, all tables were implicitly <code>Discrete</code> tables. </p> <p> This enabled me to add the first test case: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;AlternativeTableConfigurationTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;Table&nbsp;list,&nbsp;int&nbsp;list,&nbsp;int,&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Discrete&nbsp;4;&nbsp;Discrete&nbsp;1;&nbsp;Discrete&nbsp;2;&nbsp;Group&nbsp;[2;2;2]], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[3;1;2], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">true</span>) [&lt;Theory;&nbsp;ClassData(typeof&lt;AlternativeTableConfigurationTestCases&gt;)&gt;] <span style="color:blue;">let</span>&nbsp;``Alternative&nbsp;table&nbsp;configurations``&nbsp;(tables,&nbsp;rs,&nbsp;r,&nbsp;expected)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;res&nbsp;i&nbsp;=&nbsp;reserve&nbsp;(i,&nbsp;d4) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservations&nbsp;=&nbsp;List.map&nbsp;res&nbsp;rs &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;canAccept&nbsp;(1&nbsp;.days)&nbsp;(Tables&nbsp;tables)&nbsp;reservations&nbsp;(res&nbsp;r) &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;actual</pre> </p> <p> Like I did when I introduced the <code>seatingDur</code> argument, I deliberately chose a test case that didn't otherwise rock the boat too much. The same was the case now, so the only other change I had to make to pass all tests was to adjust the <code>fits</code> function: </p> <p> <pre><span style="color:green;">//&nbsp;Reservation&nbsp;-&gt;&nbsp;Table&nbsp;-&gt;&nbsp;bool</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;fits&nbsp;r&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Discrete&nbsp;seats&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity&nbsp;&lt;=&nbsp;seats &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Group&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">true</span></pre> </p> <p> It's clearly not correct to return <code>true</code> for any <code>Group</code>, but it passed all tests. </p> <h3 id="413588fbf7524177a24171c3a25f4fe7"> Accept based on sum of table group <a href="#413588fbf7524177a24171c3a25f4fe7" title="permalink">#</a> </h3> <p> I wanted to edge a little closer to correctly handling the <code>Group</code> case, so I added a test case: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;AlternativeTableConfigurationTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;Table&nbsp;list,&nbsp;int&nbsp;list,&nbsp;int,&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Discrete&nbsp;4;&nbsp;Discrete&nbsp;1;&nbsp;Discrete&nbsp;2;&nbsp;Group&nbsp;[2;2;2]], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[3;1;2], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Discrete&nbsp;4;&nbsp;Discrete&nbsp;1;&nbsp;Discrete&nbsp;2;&nbsp;Group&nbsp;[2;2;2]], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[3;1;2], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">false</span>)</pre> </p> <p> A restaurant with this table configuration can't accept a reservation for seven people, but because <code>fits</code> returned <code>true</code> for any <code>Group</code>, <code>canAccept</code> would return <code>true</code>. Since the test expected the result to be <code>false</code>, this caused the test to fail. </p> <p> Edging closer to correct behaviour, I adjusted <code>fits</code> again: </p> <p> <pre><span style="color:green;">//&nbsp;Reservation&nbsp;-&gt;&nbsp;Table&nbsp;-&gt;&nbsp;bool</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;fits&nbsp;r&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Discrete&nbsp;seats&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity&nbsp;&lt;=&nbsp;seats &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Group&nbsp;tables&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity&nbsp;&lt;=&nbsp;List.sum&nbsp;tables</pre> </p> <p> This was still not correct, because it removed an entire group of tables when <code>fits</code> returned <code>true</code>, but it passed all tests so far. </p> <h3 id="86a27564f5b846ef8dc3afdeadd613a0"> Accept reservation by combining two tables <a href="#86a27564f5b846ef8dc3afdeadd613a0" title="permalink">#</a> </h3> <p> I added another failing test: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;AlternativeTableConfigurationTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;Table&nbsp;list,&nbsp;int&nbsp;list,&nbsp;int,&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Discrete&nbsp;4;&nbsp;Discrete&nbsp;1;&nbsp;Discrete&nbsp;2;&nbsp;Group&nbsp;[2;2;2]], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[3;1;2], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Discrete&nbsp;4;&nbsp;Discrete&nbsp;1;&nbsp;Discrete&nbsp;2;&nbsp;Group&nbsp;[2;2;2]], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[3;1;2], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Discrete&nbsp;4;&nbsp;Discrete&nbsp;1;&nbsp;Discrete&nbsp;2;&nbsp;Group&nbsp;[2;2;2]], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[3;1;2;1], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;4, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">true</span>)</pre> </p> <p> The last test case failed because the existing reservations should only have reserved one of the tables in the group, but because of the way <code>fits</code> worked, the entire group was deleted by <code>Seq.deleteFirstsBy fits</code>. This made <code>canAccept</code> reject the four-person reservation. </p> <p> To be honest, this step was difficult for me. I should probably have found out how to make a smaller step. </p> <p> I wanted a function that would compare a <code>Reservation</code> to a <code>Table</code>, but unlike <code>Fits</code> return <code>None</code> if it decided to 'use' the table, or a <code>Some</code> value if it decided that it didn't need to use the entire table. This would enable me to pick only some of the tables from a <code>Group</code>, but still return a <code>Some</code> value with the rest of tables. </p> <p> I couldn't figure out an elegant way to do this with the existing <code>Seq</code> functionality, so I started to play around with something more specific. The implementation came accidentally as I was struggling to come up with something more general. As I was experimenting, all of a sudden, all tests passed! </p> <p> <pre><span style="color:green;">//&nbsp;Reservation&nbsp;-&gt;&nbsp;Table&nbsp;-&gt;&nbsp;Table&nbsp;option</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;allot&nbsp;r&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Discrete&nbsp;seats&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;r.Quantity&nbsp;&lt;=&nbsp;seats &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;None &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;Some&nbsp;(Discrete&nbsp;seats) &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Group&nbsp;tables&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Some&nbsp;(Group&nbsp;tables) <span style="color:green;">//&nbsp;seq&lt;Table&gt;&nbsp;-&gt;&nbsp;Reservation&nbsp;-&gt;&nbsp;seq&lt;Table&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;allocate&nbsp;(tables&nbsp;:&nbsp;Table&nbsp;seq)&nbsp;r&nbsp;=&nbsp;seq&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:blue;">mutable</span>&nbsp;found&nbsp;=&nbsp;<span style="color:blue;">false</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">use</span>&nbsp;e&nbsp;=&nbsp;tables.GetEnumerator&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">while</span>&nbsp;e.MoveNext&nbsp;()&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;found &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:blue;">yield</span>&nbsp;e.Current &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;allot&nbsp;r&nbsp;e.Current&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;None&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;found&nbsp;<span style="color:blue;">&lt;-</span>&nbsp;<span style="color:blue;">true</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;t&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">yield</span>&nbsp;t &nbsp;&nbsp;&nbsp;&nbsp;} <span style="color:blue;">let</span>&nbsp;canAccept&nbsp;(seatingDur&nbsp;:&nbsp;TimeSpan)&nbsp;config&nbsp;reservations&nbsp;r&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;contemporaneousReservations&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.filter&nbsp;(isContemporaneous&nbsp;seatingDur&nbsp;r)&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;config&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Communal&nbsp;capacity&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.sumBy&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity)&nbsp;contemporaneousReservations &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservedSeats&nbsp;+&nbsp;r.Quantity&nbsp;&lt;=&nbsp;capacity &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Tables&nbsp;tables&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;rs&nbsp;=&nbsp;Seq.sort&nbsp;contemporaneousReservations &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;remainingTables&nbsp;=&nbsp;Seq.fold&nbsp;allocate&nbsp;(Seq.sort&nbsp;tables)&nbsp;rs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.exists&nbsp;(fits&nbsp;r)&nbsp;remainingTables</pre> </p> <p> I wasn't too happy with the implementation, which I found (and still find) too complicated. This was, however, the first time I've done this part of the kata (in any language), so I wasn't sure where this was going. </p> <p> The <code>allocate</code> function finds and allocates one of its input tables to a reservation. It does that by <em>not</em> yielding the first table it finds that can accommodate the reservation. Don't hurt your head too much with the code in this version, because there's plenty of cases that it incorrectly handles. It's full of bugs. Still, it passed all tests. </p> <h3 id="34ef030a71e24dfabc3bd2ff0d3bdf4c"> Reject when group has been reduced <a href="#34ef030a71e24dfabc3bd2ff0d3bdf4c" title="permalink">#</a> </h3> <p> The implementation was wrong because the <code>allot</code> function would just keep returning a <code>Group</code> without consuming it. This would imply that <code>canAccept</code> would use it more than once, which was wrong, so I added a test case: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;AlternativeTableConfigurationTestCases&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;Table&nbsp;list,&nbsp;int&nbsp;list,&nbsp;int,&nbsp;bool&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do</span>&nbsp;this.Add&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Discrete&nbsp;4;&nbsp;Discrete&nbsp;1;&nbsp;Discrete&nbsp;2;&nbsp;Group&nbsp;[2;2;2]], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[3;1;2], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Discrete&nbsp;4;&nbsp;Discrete&nbsp;1;&nbsp;Discrete&nbsp;2;&nbsp;Group&nbsp;[2;2;2]], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[3;1;2], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;7, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">false</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Discrete&nbsp;4;&nbsp;Discrete&nbsp;1;&nbsp;Discrete&nbsp;2;&nbsp;Group&nbsp;[2;2;2]], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[3;1;2;1], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;4, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">true</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.Add&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Discrete&nbsp;4;&nbsp;Discrete&nbsp;1;&nbsp;Discrete&nbsp;2;&nbsp;Group&nbsp;[2;2;2]], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[3;1;2;1;4], &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">false</span>)</pre> </p> <p> Given the existing reservations, this restaurant is effectively sold out that day. All the <code>Discrete</code> tables are reserved, and the last two reservations for one and four effectively consumes the <code>Group</code>. The latest test case expected <code>canAccept</code> to return <code>false</code>, but it returned <code>true</code>. Since I was following test-driven development, I expected that. </p> <h3 id="af5554a2e5b9430cb6ec5d1aaa10ec44"> Consume <a href="#af5554a2e5b9430cb6ec5d1aaa10ec44" title="permalink">#</a> </h3> <p> I needed a function that would consume from a <code>Group</code> of tables and return the remaining tables from that group; that is, the tables not consumed. I've already <a href="/2019/12/16/zone-of-ceremony">discussed this function in a different context</a>. </p> <p> <pre><span style="color:green;">//&nbsp;int&nbsp;-&gt;&nbsp;seq&lt;int&gt;&nbsp;-&gt;&nbsp;seq&lt;int&gt;</span> <span style="color:blue;">let</span>&nbsp;consume&nbsp;quantity&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;go&nbsp;(acc,&nbsp;xs)&nbsp;x&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;quantity&nbsp;&lt;=&nbsp;acc &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;(acc,&nbsp;Seq.append&nbsp;xs&nbsp;(Seq.singleton&nbsp;x)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;(acc&nbsp;+&nbsp;x,&nbsp;xs) &nbsp;&nbsp;&nbsp;&nbsp;Seq.fold&nbsp;go&nbsp;(0,&nbsp;Seq.empty)&nbsp;&gt;&gt;&nbsp;snd</pre> </p> <p> I put this function in my own <code>Seq</code> module. It consumes values from the left until the sum is greater than or equal to the desired <code>quantity</code>. It then returns the rest of the sequence: </p> <p> <pre>&gt; consume 1 [1;2;3];; val it : seq&lt;int&gt; = seq [2; 3] &gt; consume 2 [1;2;3];; val it : seq&lt;int&gt; = seq [3] &gt; consume 3 [1;2;3];; val it : seq&lt;int&gt; = seq [3] &gt; consume 4 [1;2;3];; val it : seq&lt;int&gt; = seq []</pre> </p> <p> The first example consumes only the leading <code>1</code>, while both the second and the third example consumes both <code>1</code> and <code>2</code> because the sum of those values is <code>3</code>, and the requested quantity is <code>2</code> and <code>3</code>, respectively. The fourth example consumes all elements because the requested quantity is <code>4</code>, and you need both <code>1</code>, <code>2</code>, and <code>3</code> before the sum is large enough. You have to pick strictly from the left, so you can't decide to just take the elements <code>1</code> and <code>3</code>. </p> <h3 id="b9e29990b0fd4a5ab5e7c8812be6b07b"> Consuming tables from a group <a href="#b9e29990b0fd4a5ab5e7c8812be6b07b" title="permalink">#</a> </h3> <p> I could now use my <code>Seq.consume</code> function to improve <code>allot</code>: </p> <p> <pre><span style="color:green;">//&nbsp;Reservation&nbsp;-&gt;&nbsp;Table&nbsp;-&gt;&nbsp;Table&nbsp;option</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">private</span>&nbsp;allot&nbsp;r&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Discrete&nbsp;seats&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;r.Quantity&nbsp;&lt;=&nbsp;seats &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;None &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;Some&nbsp;(Discrete&nbsp;seats) &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Group&nbsp;tables&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;tables&nbsp;|&gt;&nbsp;Seq.consume&nbsp;r.Quantity&nbsp;|&gt;&nbsp;Seq.toList&nbsp;|&gt;&nbsp;Group&nbsp;|&gt;&nbsp;Some</pre> </p> <p> It handles the <code>Group</code> case by consuming the reservation <code>Quantity</code> and then returning a <code>Some Group</code> with the remaining tables. </p> <p> It also turned out that sorting the reservations wasn't appropriate, mainly because it's not entirely clear how to sort a list with elements of a discriminated union. My final implementation of <code>canAccept</code> was this: </p> <p> <pre><span style="color:green;">//&nbsp;TimeSpan&nbsp;-&gt;&nbsp;TableConfiguration&nbsp;-&gt;&nbsp;seq&lt;Reservation&gt;&nbsp;-&gt;&nbsp;Reservation&nbsp;-&gt;&nbsp;bool</span> <span style="color:blue;">let</span>&nbsp;canAccept&nbsp;seatingDur&nbsp;config&nbsp;reservations&nbsp;r&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;contemporaneousReservations&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.filter&nbsp;(isContemporaneous&nbsp;seatingDur&nbsp;r)&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;config&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Communal&nbsp;capacity&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.sumBy&nbsp;(<span style="color:blue;">fun</span>&nbsp;r&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;r.Quantity)&nbsp;contemporaneousReservations &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservedSeats&nbsp;+&nbsp;r.Quantity&nbsp;&lt;=&nbsp;capacity &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Tables&nbsp;tables&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;remainingTables&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.fold&nbsp;allocate&nbsp;(Seq.ofList&nbsp;tables)&nbsp;contemporaneousReservations &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Seq.exists&nbsp;(fits&nbsp;r)&nbsp;remainingTables</pre> </p> <p> Nothing much has changed - only that neither reservations nor tables are now sorted. It passes all tests. </p> <h3 id="fcba96687bac4cb3b35cbaef1b8232db"> Retrospective <a href="#fcba96687bac4cb3b35cbaef1b8232db" title="permalink">#</a> </h3> <p> I must admit that I ran out of steam towards the end. It's possible that there's some edge cases I didn't think of. I'd probably feel more confident of the final implementation if I'd used property-based testing instead of <a href="https://twitter.com/tastapod/status/1157996947581652993">Example-Guided Development</a>. </p> <p> I also took some unfortunate turns along the way. Early in the kata, I could easily implement <code>canAccept</code> with functionality from the <code>Seq</code> module. This meant that the function could take a <code>seq&lt;Reservation&gt;</code> as an input argument. I'm always inclined to follow <a href="https://en.wikipedia.org/wiki/Robustness_principle">Postel's law</a> and be liberal with what I accept. I thought that being able to accept any <code>seq&lt;Reservation&gt;</code> was a good design decision. It might have been if I'd been publishing a reusable library, but it made things more awkward. </p> <p> I'm also not sure that I chose to model the table layouts in the best way. For example, I currently can't handle a scenario with both bar seating and individual tables. I think I should have made <code>Communal</code> a case of <code>Table</code>. This would have enabled me to model layouts with several communal tables combined with discrete tables, and even groups of tables. </p> <p> In general, my solution seems too complicated, but I don't see an easy fix. Often, if I work some more with the problem, insight arrives. It usually arrives when you least need it, so I thought it better to let the problem rest for a while. I can always return to it when I feel that I have a fresh approach. </p> <h3 id="d19eccbe58924d8a96a1acab89f9bbaa"> Summary <a href="#d19eccbe58924d8a96a1acab89f9bbaa" title="permalink">#</a> </h3> <p> This article walks you through my first F# attempt at the <em>Maître d' kata</em>. The repository is available on GitHub. </p> <p> I'm not entirely happy with how it turned out, but I don't consider it an utter failure either. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="61ab9d61eb6346d39b4fcf94d094a6ef"> <div class="comment-author">Ghillie Dhu</div> <div class="comment-content"> <p> You could leverage library functions and avoid mutability like so: <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;bool)&nbsp;-&gt;&nbsp;seq&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;seq&lt;&#39;a&gt;</span> <span style="color:blue;">let</span>&nbsp;deleteFirstBy&nbsp;pred&nbsp;(xs&nbsp;:&nbsp;_&nbsp;seq)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;Seq.tryFindIndex pred xs&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;None&nbsp;<span style="color:blue;">-></span>&nbsp;xs &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;n&nbsp;<span style="color:blue;">-></span>&nbsp;Seq.concat&nbsp;(Seq.take&nbsp;(n-1)&nbsp;xs)&nbsp;(Seq.skip&nbsp;n&nbsp;xs)</pre> </p> </div> <div class="comment-date">2020-04-28 19:02 UTC</div> </div> <div class="comment" id="6fe45d2631bf410285b5403b1da737df"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Ghillie, thank you for writing. It looks like you're on the right track, but I think you have to write the function like this: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;deleteFirstBy&nbsp;pred&nbsp;(xs&nbsp;:&nbsp;_&nbsp;seq)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;Seq.tryFindIndex&nbsp;pred&nbsp;xs&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;None&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;xs &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;n&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Seq.append&nbsp;(Seq.take&nbsp;(n-1)&nbsp;xs)&nbsp;(Seq.skip&nbsp;n&nbsp;xs)</pre> </p> </div> <div class="comment-date">2020-04-28 19:21 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Unit bias against collections https://blog.ploeh.dk/2020/04/20/unit-bias-against-collections 2020-04-20T06:27:00+00:00 Mark Seemann <div id="post"> <p> <em>How do you get the value out of a collection? Mu. Which value?</em> </p> <p> The other day I was looking for documentation on how to write automated tests with a self-hosted ASP.NET Core 3 web application. I've <a href="/outside-in-tdd">done this numerous times with previous versions of the framework</a>, but ASP.NET Core 3 is new, so I wanted to learn how I'm supposed to do it this year. I found <a href="https://docs.microsoft.com/aspnet/core/test/integration-tests">official documentation</a> that helped me figure it out. </p> <p> One of the code examples in that article displays a motif that I keep encountering. It displays behaviour close enough to <em>unit bias</em> that I consider it reasonable to use that label. Unit bias is the cognitive tendency to consider a <em>unit</em> of something the preferred amount. Our brains don't like fractions, and they don't like multiples either. </p> <h3 id="c9468b526bcb444a99680d8a6a5deb29"> Unit bias in action <a href="#c9468b526bcb444a99680d8a6a5deb29" title="permalink">#</a> </h3> <p> The sample code in the ASP.NET Core documentation differs in the type of dependency it looks for, but is otherwise identical to this: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">descriptor</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">services</span>.<span style="font-weight:bold;color:#74531f;">SingleOrDefault</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">d</span>&nbsp;=&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">d</span>.ServiceType&nbsp;<span style="font-weight:bold;color:#74531f;">==</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">typeof</span>(<span style="color:#2b91af;">IReservationsRepository</span>)); <span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">descriptor</span>&nbsp;!=&nbsp;<span style="color:blue;">null</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">services</span>.<span style="font-weight:bold;color:#74531f;">Remove</span>(<span style="font-weight:bold;color:#1f377f;">descriptor</span>); }</pre> </p> <p> The goal is to enable an automated integration test to <a href="/2019/04/01/an-example-of-state-based-testing-in-c">run against a Fake database</a> instead of an actual relational database. My production <a href="/2011/07/28/CompositionRoot">Composition Root</a> registers an implementation of <code>IReservationsRepository</code> that communicates with an actual database. In an automated integration test, I'd like to unregister the existing dependency and replace it with <a href="http://xunitpatterns.com/Fake%20Object.html">a Fake</a>. Here's the code in context: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">RestaurantApiFactory</span>&nbsp;:&nbsp;<span style="color:#2b91af;">WebApplicationFactory</span>&lt;<span style="color:#2b91af;">Startup</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">protected</span>&nbsp;<span style="color:blue;">override</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">ConfigureWebHost</span>(<span style="color:#2b91af;">IWebHostBuilder</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">builder</span>&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#1f377f;">builder</span>)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">ConfigureServices</span>(<span style="font-weight:bold;color:#1f377f;">services</span>&nbsp;=&gt; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">descriptor</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">services</span>.<span style="font-weight:bold;color:#74531f;">SingleOrDefault</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">d</span>&nbsp;=&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">d</span>.ServiceType&nbsp;<span style="font-weight:bold;color:#74531f;">==</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">typeof</span>(<span style="color:#2b91af;">IReservationsRepository</span>)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">descriptor</span>&nbsp;!=&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">services</span>.<span style="font-weight:bold;color:#74531f;">Remove</span>(<span style="font-weight:bold;color:#1f377f;">descriptor</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">services</span>.<span style="font-weight:bold;color:#74531f;">AddSingleton</span>&lt;<span style="color:#2b91af;">IReservationsRepository</span>&gt;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">FakeDatabase</span>()); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> It works as intended, so what's the problem? </p> <h3 id="d84651bde63944e9bb04873f51a58085"> How do I get the value out of my collection? <a href="#d84651bde63944e9bb04873f51a58085" title="permalink">#</a> </h3> <p> The problem is that it's fragile. What happens if there's more than one registration of <code>IReservationsRepository</code>? </p> <p> This happens: </p> <p> <pre>System.InvalidOperationException : Sequence contains more than one matching element</pre> </p> <p> This is a completely avoidable error, stemming from unit bias. </p> <p> A large proportion of programmers I meet seem to be fundamentally uncomfortable with thinking in multitudes. They subconsciously prefer thinking in procedures and algorithms that work on a single object. The programmer who wrote the above call to <a href="https://docs.microsoft.com/dotnet/api/system.linq.enumerable.singleordefault">SingleOrDefault</a> exhibits behaviour putting him or her in that category. </p> <p> This is nothing but a specific instantiation of a more general programmer bias: <a href="/2019/02/04/how-to-get-the-value-out-of-the-monad">How do I get the value out of the monad?</a> </p> <p> As usual, the answer is <a href="https://en.wikipedia.org/wiki/Mu_(negative)">mu</a>. You don't. The question borders on the nonsensical. <em>How do I get the value out of my collection?</em> Which value? The first? The last? Some arbitrary value at an unknown position? Which value do you want if the collection is empty? Which value do you want if there's more than one that fits a predicate? </p> <p> If you can answer such questions, you <em>can</em> get 'the' value out of a collection, but often, you can't. In the current example, the code doesn't handle multiple <code>IReservationsRepository</code> registrations. </p> <p> It easily could, though. </p> <h3 id="568f351c446f4e33a158eccdfbb461e6"> Inject the behaviour into the collection <a href="#568f351c446f4e33a158eccdfbb461e6" title="permalink">#</a> </h3> <p> The best answer to the question of <em>how to get the value out of the monad</em> (in this case, <em>the collection</em>) is that you don't. Instead, you inject the desired behaviour into it. </p> <p> In this case, the desired behaviour is to remove a <code>descriptor</code>. The monad in question is the collection of <code>services</code>. What does that mean in practice? </p> <p> A first attempt might be something like this: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">descriptors</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">services</span> &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Where</span>(<span style="font-weight:bold;color:#1f377f;">d</span>&nbsp;=&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">d</span>.ServiceType&nbsp;<span style="font-weight:bold;color:#74531f;">==</span>&nbsp;<span style="color:blue;">typeof</span>(<span style="color:#2b91af;">IReservationsRepository</span>)); <span style="font-weight:bold;color:#8f08c4;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">descriptor</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">in</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">descriptors</span>) &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">services</span>.<span style="font-weight:bold;color:#74531f;">Remove</span>(<span style="font-weight:bold;color:#1f377f;">descriptor</span>);</pre> </p> <p> Unfortunately, this doesn't quite work: </p> <p> <pre>System.InvalidOperationException : Collection was modified; enumeration operation may not execute.</pre> </p> <p> This happens because <code>descriptors</code> is a lazily evaluated <a href="https://en.wikipedia.org/wiki/Iterator_pattern">Iterator</a> over <code>services</code>, and you're not allowed to remove elements from a collection while you enumerate it. It could lead to bugs if you could. </p> <p> That problem is easily solved. Just copy the selected <code>descriptors</code> to an array or list: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">descriptors</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">services</span> &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Where</span>(<span style="font-weight:bold;color:#1f377f;">d</span>&nbsp;=&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">d</span>.ServiceType&nbsp;<span style="font-weight:bold;color:#74531f;">==</span>&nbsp;<span style="color:blue;">typeof</span>(<span style="color:#2b91af;">IReservationsRepository</span>)) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">ToList</span>(); <span style="font-weight:bold;color:#8f08c4;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">descriptor</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">in</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">descriptors</span>) &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">services</span>.<span style="font-weight:bold;color:#74531f;">Remove</span>(<span style="font-weight:bold;color:#1f377f;">descriptor</span>);</pre> </p> <p> This achieves the desired outcome regardless of the number of matches to the predicate. This is a more robust solution, and it requires the same amount of code. </p> <p> You can stop there, since the code now works, but if you truly want to <em>inject the behaviour into the collection</em>, you're not quite done yet. </p> <p> But you're close. All you have to do is this: </p> <p> <pre><span style="font-weight:bold;color:#1f377f;">services</span> &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Where</span>(<span style="font-weight:bold;color:#1f377f;">d</span>&nbsp;=&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">d</span>.ServiceType&nbsp;<span style="font-weight:bold;color:#74531f;">==</span>&nbsp;<span style="color:blue;">typeof</span>(<span style="color:#2b91af;">IReservationsRepository</span>)) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">ToList</span>() &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">ForEach</span>(<span style="font-weight:bold;color:#1f377f;">d</span>&nbsp;=&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">services</span>.<span style="font-weight:bold;color:#74531f;">Remove</span>(<span style="font-weight:bold;color:#1f377f;">d</span>));</pre> </p> <p> Notice how this statement never produces an output. Instead, you 'inject' the call to <code>services.Remove</code> into the list, using the <a href="https://docs.microsoft.com/dotnet/api/system.collections.generic.list-1.foreach">ForEach</a> method, which then mutates the <code>services</code> collection. </p> <p> Whether you prefer the version that uses the <code>foreach</code> keyword or the version that uses <code>List&lt;T&gt;.ForEach</code> doesn't matter. What matters is that you don't use the <a href="https://en.wikipedia.org/wiki/Partial_function">partial</a> <code>SingleOrDefault</code> function. </p> <h3 id="cd80281860ed4b8299278cdaa2e65709"> Conclusion <a href="#cd80281860ed4b8299278cdaa2e65709" title="permalink">#</a> </h3> <p> It's a common code smell when programmers try to extract a single value from a collection. Sometimes it's appropriate, but there are several edge cases you should be prepared to address. What should happen if the collection is empty? What should happen if the collection contains many elements? What should happen if the collection is infinite? (I didn't address that in this article.) </p> <p> You can often both simplify your code and make it more robust by staying 'in' the collection, so to speak. Let the desired behaviour apply to all appropriate elements of the collection. </p> <p> Don't be biased against collections. </p> </div> <hr> <div id="comments"> <h2 id="comments-header"> Comments </h2> <div class="comment" id="e6675033a3a9dc8a21c64650dff91b8432a9a151"> <div class="comment-author">Julius H</div> <div class="comment-content"> <p>I concur that often the first element of a collection is picked without thinking. Anecdotally, I experienced a system that would not work if set up freshly because in some places there was no consideration for empty collections. (The testing environment always contained some data)</p> <p> Yet I would reverse the last change (towards <code>.ForEach</code>). For one, because (to my biased eye) it <i>looks</i> side effect free but isn't. And then it does add value compared to a forech loop, also both solutions are needlessy inefficient. If you want to avoid the foreach, go for the <code>RemoveAll()</code> method (also present on List&lt;T&gt;): </p> <pre> services.<span style="font-weight:bold;color:#74531f;">RemoveAll</span>&lt;<span style="color:#2b91af;">IReservationsRepository</span>&gt;(); </pre> </p> </div> <div class="comment-date">2020-04-29 8:52 UTC</div> </div> <div class="comment" id="99baee4e923b471891eef04b499b64a1"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Julius, thank you for writing. Yes, I agree that in C# it's more <a href="/2015/08/03/idiomatic-or-idiosyncratic">idiomatic</a> to use <code>foreach</code>. </p> <p> How would using <code>RemoveAll</code> work? Isn't that going to remove the entries from the <code>List</code> instead of from <code>services</code>? </p> </div> <div class="comment-date">2020-04-29 10:49 UTC</div> </div> <div class="comment" id="17b7d3a21cff5b6585d6d2fa0f63f1539f9bce3e"> <div class="comment-author">Julius H</div> <div class="comment-content"> <p> Hi Mark,<br />As you&quot;re calling <a href="https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.dependencyinjection.extensions.servicecollectiondescriptorextensions.removeall?view=dotnet-plat-ext-3.1"><code>IServiceCollection.RemoveAll()</code></a>, it will remove it from the collection. I tried it, and to me it seems to be working. (As long as you are not copying the services into a list beforehand) </p> <p> But to your main point, I remember when I wrote <code>.Single()</code> once, and years later I got a bug report because of it. I see two approaches there: Fail as fast and hard as possible or check just as much as needed for the moment. Considering TDD in the former approach, one would need to write a lot of test code for scenarios, that should never happen to verify the exceptions happen. Still, in the latter approach, a subtle bug could stay in the system for quite some time... What do you prefer? </p> </div> <div class="comment-date">2020-05-01 18:07 UTC</div> </div> <div class="comment" id="3eed1b53957e4abf8b92c83c15e63ec6"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Julius, thank you for writing. It turns out that <code>RemoveAll</code> are <a href="https://docs.microsoft.com/dotnet/api/microsoft.extensions.dependencyinjection.extensions.servicecollectiondescriptorextensions.removeall">a couple of extension methods on <code>IServiceCollection</code></a>. One has to import <code>Microsoft.Extensions.DependencyInjection.Extensions</code> with a <code>using</code> directive before one can use them. I didn't know about these methods, but I agree that they seem to do their job. Thank you for the tip. </p> <p> As for your question, my preference is for robustness. In my experience, there's rarely such a thing as a scenario that never happens. If the code allows something to happen, it'll likely happen sooner or later. Code changes, so even if you've analysed that some combination of input isn't possible today, a colleague may change the situation tomorrow. It pays to write that extra unit test or two to make sure that encapsulation isn't broken. </p> <p> This is also one of the reasons I'm fond of <a href="/property-based-testing-intro">property-based testing</a>. You automatically get coverage of all sorts of boundary conditions you'd normally not think about testing. </p> </div> <div class="comment-date">2020-05-02 9:12 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Curb code rot with thresholds https://blog.ploeh.dk/2020/04/13/curb-code-rot-with-thresholds 2020-04-13T08:43:00+00:00 Mark Seemann <div id="post"> <p> <em>Code bases deteriorate unless you actively prevent it. Institute some limits that encourage developers to clean up.</em> </p> <p> From time to time I manage to draw the ire of people, with articles such as <a href="/2019/11/04/the-80-24-rule">The 80/24 rule</a> or <a href="/2019/12/09/put-cyclomatic-complexity-to-good-use">Put cyclomatic complexity to good use</a>. I can understand why. These articles suggest specific constraints to which people should consider consenting. <em>Don't write code wider than 80 characters. Don't write code with a <a href="https://en.wikipedia.org/wiki/Cyclomatic_complexity">cyclomatic complexity</a> higher than 7</em>. </p> <p> It makes people uncomfortable. </p> <h3 id="6c5e4b0817f742bf9ecc0a9050ecb7b5"> Sophistication <a href="#6c5e4b0817f742bf9ecc0a9050ecb7b5" title="permalink">#</a> </h3> <p> I hope that regular readers understand that I'm a more sophisticated thinker than some of my texts may suggest. I deliberately simplify my points. </p> <p> I do this to make the text more readable. I also aspire to present sufficient arguments, and enough context, that a charitable reader will understand that everything I write should be taken as food for thought rather than gospel. </p> <p> Consider a sentence like the above: <em>I deliberately simplify my points</em>. That sentence, in itself, is an example of deliberate simplification. In reality, I don't <em>always</em> simplify my points. Perhaps sometimes I simplify, but it's not <em>deliberate</em>. I could have written: <em>I often deliberately simplify some of my points</em>. Notice the extra <a href="https://en.wikipedia.org/wiki/Hedge_(linguistics)">hedge words</a>. Imagine an entire text written like that. It would be less readable. </p> <p> I could hedge my words when I write articles, but I don't. I believe that a text that states its points as clearly as possible is easier to understand for any careful reader. I also believe that hedging my language will not prevent casual readers from misunderstanding what I had in mind. </p> <h3 id="a5da32d0580d4a0f8c19069c57c2a335"> Archetypes <a href="#a5da32d0580d4a0f8c19069c57c2a335" title="permalink">#</a> </h3> <p> Why do I suggest hard limits on line width, cyclomatic complexity, and so on? </p> <p> In light of the above, realise that the limits I offer are suggestions. A number like 80 characters isn't a hard limit. It's a representation of an idea; a token. The same is true for <a href="https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two">the magic number seven, plus or minus two</a>. That too, represents an idea - the idea that human short-term memory is limited, and that this impacts our ability to read and understand code. </p> <p> The number seven serves as an archetype. It's a proxy for a more complex idea. It's a simplification that, hopefully, makes it easier to follow the plot. </p> <p> <em>Each method should have a maximum cyclomatic complexity of seven.</em> That's easier to understand than <em>each method should have a maximum cyclomatic complexity small enough that it fits within the cognitive limits of the human brain's short-term memory</em>. </p> <p> I've noticed that a subset of the developer population is quite literal-minded. If I declare: <em>don't write code wider than 80 characters</em> they're happy if they agree, and infuriated if they don't. </p> <p> If you've been paying attention, you now understand that this isn't about the number <em>80</em>, or <em>24</em>, or <em>7</em>. It's about instituting useful quantitative guidance. The actual number is less important. </p> <p> I have reasons to prefer those specific values. I've already motivated them in previous articles. I'm not, though, obdurately attached to those particular numbers. I'd rather work with a team that has agreed to a 120-character maximum width than with a team that follows no policy. </p> <h3 id="8b7d0a456f6f4bdca9ea2814a67144fc"> How code rots <a href="#8b7d0a456f6f4bdca9ea2814a67144fc" title="permalink">#</a> </h3> <p> No-one deliberately decides to write legacy code. Code bases gradually deteriorate. </p> <p> Here's another deliberate simplification: code gradually becomes more complicated because each change seems small, and no-one pays attention to the overall quality. It doesn't happen overnight, but one day you realise that you've developed a legacy code base. When that happens, it's too late to do anything about it. </p> <p> <img src="/content/binary/gradual-increase-of-complexity.png" alt="Line chart showing increasing complexity as time passes."> </p> <p> At the beginning, a method has low complexity, but as you fix defects and add features, the complexity increases. If you don't pay attention to cyclomatic complexity, you pass <em>7</em> without noticing it. You pass <em>10</em> without noticing it. You pass <em>15</em> and <em>20</em> without noticing it. </p> <p> One day you discover that you have a problem - not because you finally look at a metric, but because the code has now become so complicated that everyone notices. Alas, now it's too late to do anything about it. </p> <p> <a href="https://en.wikipedia.org/wiki/Software_rot">Code rot</a> sets in a little at a time; it works like <a href="https://en.wikipedia.org/wiki/Boiling_frog">boiling the proverbial frog</a>. </p> <h3 id="4fd818d9459548a7863f38ebdd6c40f8"> Thresholds <a href="#4fd818d9459548a7863f38ebdd6c40f8" title="permalink">#</a> </h3> <p> Agreeing on a threshold can help curb code rot. Institute a rule and monitor a metric. For example, you could agree to keep an eye on cyclomatic complexity. If it exceeds <em>7</em>, you reject the change. </p> <p> <img src="/content/binary/development-of-complexity-guarded-by-threshold.png" alt="Line chart showing how complexity is curbed by a threshold of 7."> </p> <p> Such rules work because they can be used to counteract gradual decay. It's not the specific value <em>7</em> that contributes to better <a href="/2019/03/04/code-quality-is-not-software-quality">code quality</a>; it's the automatic activation of a rule based on a threshold. If you decide that the threshold should be <em>10</em> instead, that'll also make a difference. </p> <p> Notice that the above diagram suggests that exceeding the threshold is still possible. Rules are in the way if you must rigidly obey them. Situations arise where breaking a rule is the best response. Once you've responded to the situation, however, find a way to bring the offending code back in line. Once a threshold is exceeded, you don't get any further warnings, and there's a risk that that particular code will gradually decay. </p> <h3 id="431b3a30bb6448b6b34c06a169b6fefb"> What you measure is what you get <a href="#431b3a30bb6448b6b34c06a169b6fefb" title="permalink">#</a> </h3> <p> You could automate the process. Imagine running cyclomatic complexity analysis as part of a Continuous Integration build and rejecting changes that exceed a threshold. This is, in a way, a deliberate attempt to hack the management effect where you get what you measure. With emphasis on a metric like cyclomatic complexity, developers will pay attention to it. </p> <p> Be aware, however, of <a href="https://en.wikipedia.org/wiki/Goodhart%27s_law">Goodhart's law</a> and <a href="https://en.wikipedia.org/wiki/Unintended_consequences">the law of unintended consequences</a>. Just as <a href="/2015/11/16/code-coverage-is-a-useless-target-measure">code coverage is a useless target measure</a>, you have to be careful when you institute hard rules. </p> <p> I've had success with introducing threshold rules because they increase awareness. It can help a technical leader shift emphasis to the qualities that he or she wishes to improve. Once the team's mindset has changed, the rule itself becomes redundant. </p> <p> I'm reminded of <a href="https://en.wikipedia.org/wiki/Dreyfus_model_of_skill_acquisition">the Dreyfus model of skill acquisition</a>. Rules make great training wheels. Once you become proficient, the rules are no longer required. They may even be in your way. When that happens, get rid of them. </p> <h3 id="97ad7bcd44644a05b78c75e82a3c4ad7"> Conclusion <a href="#97ad7bcd44644a05b78c75e82a3c4ad7" title="permalink">#</a> </h3> <p> Code deteriorates gradually, when you aren't looking. Instituting rules that make you pay attention can combat code rot. Using thresholds to activate your attention can be an effective countermeasure. The specific value of the threshold is less important. </p> <p> In this article, I've mostly used cyclomatic complexity as an example of a metric where a threshold could be useful. Another example is line width; don't exceed 80 characters. Or line height: methods shouldn't exceed 24 lines of code. Those are examples. If you agree that keeping an eye on a metric would be useful, but you disagree with the threshold I suggest, pick a value that suits you better. </p> <p> It's not the specific threshold value that improves your code; paying attention does. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Repeatable execution in C# https://blog.ploeh.dk/2020/04/06/repeatable-execution-in-c 2020-04-06T07:46:00+00:00 Mark Seemann <div id="post"> <p> <em>A C# example of Goldilogs.</em> </p> <p> This article is part of <a href="/2020/03/23/repeatable-execution">a series of articles about repeatable execution</a>. The introductory article argued that if you've logged the impure actions that a system made, you have enough information to reproduce what happened. The <a href="/2020/03/30/repeatable-execution-in-haskell">previous article</a> verified that for the example scenario, the impure actions were limited to reading the current time and interacting with the application database. </p> <p> This article shows how to implement equivalent functionality in C#. You should be able to extrapolate from this to other object-oriented programming languages. </p> <p> The code is <a href="https://github.com/ploeh/reservation-api-slice-csharp">available on GitHub</a>. </p> <h3 id="338d728ddae0410dbb7fefccd6781f6f"> Impure actions <a href="#338d728ddae0410dbb7fefccd6781f6f" title="permalink">#</a> </h3> <p> In the previous article I <a href="/2017/07/10/pure-interactions">modelled impure actions as free monads</a>. In C#, it'd be more <a href="/2015/08/03/idiomatic-or-idiosyncratic">idiomatic</a> to <a href="/2017/01/27/from-dependency-injection-to-dependency-rejection">use Dependency Injection</a>. Model each impure interaction as an interface. </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IClock</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">DateTime</span>&nbsp;<span style="font-weight:bold;color:#74531f;">GetCurrentDateTime</span>(); }</pre> </p> <p> The demo code demonstrates a single feature of a REST API and it only requires a single method on this interface to work. Following the <a href="https://en.wikipedia.org/wiki/Dependency_inversion_principle">Dependency Inversion Principle</a> <blockquote> <p> "clients [...] own the abstract interfaces" </p> <footer><cite><a href="http://amzn.to/19W4JHk">Agile Principles, Patterns, and Practices</a>, chapter 11</cite></footer> </blockquote> This interface only defines a single method, because that's all the client code requires. </p> <p> Likewise, the client code only needs two methods to interact with the database: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IReservationsRepository</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="font-weight:bold;color:#74531f;">ReadReservations</span>(<span style="color:#2b91af;">DateTime</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">date</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Create</span>(<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>); }</pre> </p> <p> In the Haskell example code base, I also implemented <code>GET</code> for <code>/reservations</code>, but I forgot to do that here. There's only two methods on the interface: one to query the database, and one to create a new row. </p> <h3 id="63f39b6964f74a9c847913f4e1b5359c"> Receive a reservation <a href="#63f39b6964f74a9c847913f4e1b5359c" title="permalink">#</a> </h3> <p> The central feature of the service is to receive and handle an HTTP POST request, as described in the introductory article. When a document arrives it triggers a series of non-trivial work: <ol> <li>The service validates the input data. Among other things, it checks that the reservation is in the future. It uses <code>GetCurrentDateTime</code> for this.</li> <li>It queries the database for existing reservations. It uses <code>ReadReservations</code> for this.</li> <li>It uses complex business logic to determine whether to accept the reservation. This essentially implements the <a href="/2020/01/27/the-maitre-d-kata">Ma&icirc;tre d' kata</a>.</li> <li>If it accepts the reservation, it stores it. It uses <code>Create</code> for this.</li> </ol> These steps manifest as this Controller method: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">ActionResult</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Post</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:blue;">_</span>)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BadRequest</span>(<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Mapper</span>.<span style="color:#74531f;">Map</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date&nbsp;<span style="font-weight:bold;color:#74531f;">&lt;</span>&nbsp;Clock.<span style="font-weight:bold;color:#74531f;">GetCurrentDateTime</span>()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BadRequest</span>(<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date}<span style="color:#a31515;">.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservations</span>&nbsp;=&nbsp;Repository.<span style="font-weight:bold;color:#74531f;">ReadReservations</span>(<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">accepted</span>&nbsp;=&nbsp;maîtreD.<span style="font-weight:bold;color:#74531f;">CanAccept</span>(<span style="font-weight:bold;color:#1f377f;">reservations</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="font-weight:bold;color:#1f377f;">accepted</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">StatusCode</span>(<span style="color:#2b91af;">StatusCodes</span>.Status500InternalServerError,&nbsp;<span style="color:#a31515;">&quot;Couldn&#39;t&nbsp;accept.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;Repository.<span style="font-weight:bold;color:#74531f;">Create</span>(<span style="font-weight:bold;color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Ok</span>(); }</pre> </p> <p> <code>Clock</code> and <code>Repository</code> are injected dependencies, and <code>maîtreD</code> is an object that implements the decision logic as the <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a> <code>CanAccept</code> function. </p> <h3 id="c7042ff0e8c246cc8a9f12e656a4bf54"> Composition <a href="#c7042ff0e8c246cc8a9f12e656a4bf54" title="permalink">#</a> </h3> <p> The <code>Post</code> method is defined on a class called <code>ReservationsController</code> with these dependencies: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">ReservationsController</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">TimeSpan</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">seatingDuration</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:#2b91af;">Table</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">tables</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IReservationsRepository</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">repository</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IClock</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">clock</span>)</pre> </p> <p> The <code>seatingDuration</code> and <code>tables</code> arguments are <a href="/2012/07/02/PrimitiveDependencies">primitive dependencies</a> used to configure the <code>maîtreD</code> object. I could also have injected <code>maîtreD</code> as a <a href="/2012/08/31/ConcreteDependencies">concrete dependency</a>, but I decided against that for no particular reason. </p> <p> There's no logging dependency, but the system still logs. Like in the previous example, logging is a cross-cutting concern and exclusively addressed through composition: </p> <p> <pre><span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">controllerType</span>&nbsp;<span style="font-weight:bold;color:#74531f;">==</span>&nbsp;<span style="color:blue;">typeof</span>(<span style="color:#2b91af;">ReservationsController</span>)) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">l</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ScopedLog</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">FileLog</span>(LogFile)); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">controller</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ReservationsController</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SeatingDuration, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Tables, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">LogReservationsRepository</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlReservationsRepository</span>(ConnectionString), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">l</span>), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">LogClock</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SystemClock</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">l</span>)); &nbsp;&nbsp;&nbsp;&nbsp;Logs.<span style="font-weight:bold;color:#74531f;">AddOrUpdate</span>(<span style="font-weight:bold;color:#1f377f;">controller</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">l</span>,&nbsp;(<span style="font-weight:bold;color:#1f377f;">_</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>)&nbsp;=&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">controller</span>; }</pre> </p> <p> Each dependency is wrapped by a logger. We'll return to that in a minute, but consider first the actual implementations. </p> <h3 id="40cf79001f6f4982ba694efe324cb2b1"> Using the system clock <a href="#40cf79001f6f4982ba694efe324cb2b1" title="permalink">#</a> </h3> <p> Using the system clock is easy: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">SystemClock</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IClock</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">DateTime</span>&nbsp;<span style="font-weight:bold;color:#74531f;">GetCurrentDateTime</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#2b91af;">DateTime</span>.Now; &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> This implementation of <code>IClock</code> simply delegates to <code>DateTime.Now</code>. Again, no logging service is injected. </p> <h3 id="392b67a393cc4deaad9b19901ea4c4c4"> Using the database <a href="#392b67a393cc4deaad9b19901ea4c4c4" title="permalink">#</a> </h3> <p> Using the database isn't much harder. I don't find that <a href="https://en.wikipedia.org/wiki/Object-relational_mapping">ORMs</a> offer any benefits, so I prefer to implement database functionality using basic database APIs: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Create</span>(<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">using</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">conn</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlConnection</span>(ConnectionString)) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">using</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">cmd</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlCommand</span>(createReservationSql,&nbsp;<span style="font-weight:bold;color:#1f377f;">conn</span>)) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">cmd</span>.Parameters.<span style="font-weight:bold;color:#74531f;">Add</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Guid&quot;</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>.Id)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">cmd</span>.Parameters.<span style="font-weight:bold;color:#74531f;">Add</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Date&quot;</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">cmd</span>.Parameters.<span style="font-weight:bold;color:#74531f;">Add</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Name&quot;</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>.Name)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">cmd</span>.Parameters.<span style="font-weight:bold;color:#74531f;">Add</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Email&quot;</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>.Email)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">cmd</span>.Parameters.<span style="font-weight:bold;color:#74531f;">Add</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">SqlParameter</span>(<span style="color:#a31515;">&quot;@Quantity&quot;</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>.Quantity)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">conn</span>.<span style="font-weight:bold;color:#74531f;">Open</span>(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">cmd</span>.<span style="font-weight:bold;color:#74531f;">ExecuteNonQuery</span>(); &nbsp;&nbsp;&nbsp;&nbsp;} } <span style="color:blue;">private</span>&nbsp;<span style="color:blue;">const</span>&nbsp;<span style="color:blue;">string</span>&nbsp;createReservationSql&nbsp;=&nbsp;<span style="color:maroon;">@&quot; &nbsp;&nbsp;&nbsp;&nbsp;INSERT&nbsp;INTO&nbsp;[dbo].[Reservations]&nbsp;([Guid],&nbsp;[Date],&nbsp;[Name],&nbsp;[Email],&nbsp;[Quantity]) &nbsp;&nbsp;&nbsp;&nbsp;OUTPUT&nbsp;INSERTED.Id &nbsp;&nbsp;&nbsp;&nbsp;VALUES&nbsp;(@Guid,&nbsp;@Date,&nbsp;@Name,&nbsp;@Email,&nbsp;@Quantity)&quot;</span>;</pre> </p> <p> The above code snippet implements the <code>Create</code> method of the <code>IReservationsRepository</code> interface. Please refer to the Git repository for the full code if you need more details. </p> <p> If you prefer to implement your database functionality with an ORM, or in another way, you can do that. It doesn't change the architecture of the system. No logging service is required to interact with the database. </p> <h3 id="e70ddcfa03c04444931f0b3737e09101"> Compose with logging <a href="#e70ddcfa03c04444931f0b3737e09101" title="permalink">#</a> </h3> <p> As the above composition code snippet suggests, logging is implemented with <a href="https://en.wikipedia.org/wiki/Decorator_pattern">Decorators</a>. The ultimate implementation of <code>IClock</code> is <code>SystemClock</code>, but the <a href="/2011/07/28/CompositionRoot">Composition Root</a> decorates it with <code>LogClock</code>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">LogClock</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IClock</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">LogClock</span>(<span style="color:#2b91af;">IClock</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">inner</span>,&nbsp;<span style="color:#2b91af;">ScopedLog</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">log</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Inner&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">inner</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Log&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">log</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IClock</span>&nbsp;Inner&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">ScopedLog</span>&nbsp;Log&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">DateTime</span>&nbsp;<span style="font-weight:bold;color:#74531f;">GetCurrentDateTime</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">currentDateTime</span>&nbsp;=&nbsp;Inner.<span style="font-weight:bold;color:#74531f;">GetCurrentDateTime</span>(); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Observe</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Interaction</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Operation&nbsp;=&nbsp;<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#74531f;">GetCurrentDateTime</span>), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Output&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">currentDateTime</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">currentDateTime</span>; &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> <code>ScopedLog</code> is a Concrete Dependency that, among other members, affords the <code>Observe</code> method. Notice that <code>LogClock</code> implements <code>IClock</code> by decorating another polymorphic <code>IClock</code> instance. It delegates functionality to <code>inner</code>, logs the <code>currentDateTime</code> and returns it. </p> <p> The <code>LogReservationsRepository</code> class implements the same pattern: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">LogReservationsRepository</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IReservationsRepository</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">LogReservationsRepository</span>(<span style="color:#2b91af;">IReservationsRepository</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">inner</span>,&nbsp;<span style="color:#2b91af;">ScopedLog</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">log</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Inner&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">inner</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Log&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">log</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IReservationsRepository</span>&nbsp;Inner&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">ScopedLog</span>&nbsp;Log&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Create</span>(<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Observe</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Interaction</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Operation&nbsp;=&nbsp;<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#74531f;">Create</span>), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Input&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;{&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Inner.<span style="font-weight:bold;color:#74531f;">Create</span>(<span style="font-weight:bold;color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="font-weight:bold;color:#74531f;">ReadReservations</span>(<span style="color:#2b91af;">DateTime</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">date</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservations</span>&nbsp;=&nbsp;Inner.<span style="font-weight:bold;color:#74531f;">ReadReservations</span>(<span style="font-weight:bold;color:#1f377f;">date</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Observe</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Interaction</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Operation&nbsp;=&nbsp;<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#74531f;">ReadReservations</span>), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Input&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;{&nbsp;<span style="font-weight:bold;color:#1f377f;">date</span>&nbsp;}, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Output&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">reservations</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservations</span>; &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> This architecture not only implements the desired functionality, but also <em>Goldilogs</em>: not too little, not too much, but just what you need. Notice that I didn't have to change any of my Domain Model or HTTP-specific code to enable logging. This cross-cutting concern is enabled entirely via composition. </p> <h3 id="59b912d918c9451e97e09b8274d7fb87"> Repeatability <a href="#59b912d918c9451e97e09b8274d7fb87" title="permalink">#</a> </h3> <p> An HTTP request like this: </p> <p> <pre>POST /reservations/ HTTP/1.1 Content-Type: application/json { &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;id&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;7bc3fc93-a777-4138-8630-a805e7246335&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;date&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2020-03-20&nbsp;18:45:00&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;name&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;Kozue Kaburagi&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;email&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;ninjette@example.net&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;quantity&quot;</span>:&nbsp;4 }</pre> </p> <p> produces a log entry like this: </p> <p> <pre>{ &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;entry&quot;</span>:&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;time&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2020-01-02T09:50:34.2678703+01:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;operation&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;Post&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;input&quot;</span>:&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;dto&quot;</span>:&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;id&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;7bc3fc93-a777-4138-8630-a805e7246335&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;date&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2020-03-20&nbsp;18:45:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;email&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;ninjette@example.net&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;name&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;Kozue Kaburagi&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;quantity&quot;</span>:&nbsp;4 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;}, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;output&quot;</span>:&nbsp;<span style="color:blue;">null</span> &nbsp;&nbsp;}, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;interactions&quot;</span>:&nbsp;[ &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;time&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2020-01-02T09:50:34.2726143+01:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;operation&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;GetCurrentDateTime&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;input&quot;</span>:&nbsp;<span style="color:blue;">null</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;output&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2020-01-02T09:50:34.2724012+01:00&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;}, &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;time&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2020-01-02T09:50:34.3571224+01:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;operation&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;ReadReservations&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;input&quot;</span>:&nbsp;{&nbsp;<span style="color:#2e75b6;">&quot;date&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2020-03-20T18:45:00&quot;</span>&nbsp;}, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;output&quot;</span>:&nbsp;[ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;id&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;c3cbfbc7-6d64-4ead-84ef-7f89de5b7e1c&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;date&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2020-03-20T19:00:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;email&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;emp@example.com&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;name&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;Elissa&nbsp;Megan&nbsp;Powers&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;quantity&quot;</span>:&nbsp;3 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;] &nbsp;&nbsp;&nbsp;&nbsp;}, &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;time&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2020-01-02T09:50:34.3587586+01:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;operation&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;Create&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;input&quot;</span>:&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;reservation&quot;</span>:&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;id&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;7bc3fc93-a777-4138-8630-a805e7246335&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;date&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2020-03-20T18:45:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;email&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;ninjette@example.net&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;name&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;Kozue Kaburagi&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;quantity&quot;</span>:&nbsp;4 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;output&quot;</span>:&nbsp;<span style="color:blue;">null</span> &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;], &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;exit&quot;</span>:&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;time&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2020-01-02T09:50:34.3645105+01:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;operation&quot;</span>:&nbsp;<span style="color:blue;">null</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;input&quot;</span>:&nbsp;<span style="color:blue;">null</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2e75b6;">&quot;output&quot;</span>:&nbsp;{&nbsp;<span style="color:#2e75b6;">&quot;statusCode&quot;</span>:&nbsp;200&nbsp;} &nbsp;&nbsp;} }</pre> </p> <p> I chose to gather all information regarding a single HTTP request into a single log entry and format it as JSON. I once worked with an organisation that used the ELK stack in that way, and it made it easy to identify and troubleshoot issues in production. </p> <p> You can use such a log file to reproduce the observed behaviour, for example in a unit test: </p> <p> <pre>[<span style="color:#2b91af;">Fact</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">NinjetteRepro</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">log</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Log</span>.<span style="color:#74531f;">LoadFile</span>(<span style="color:#a31515;">&quot;Ninjette.json&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:#2b91af;">ReservationsController</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sut</span>,&nbsp;<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Log</span>.<span style="color:#74531f;">LoadReservationsControllerPostScenario</span>(<span style="font-weight:bold;color:#1f377f;">log</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">sut</span>.<span style="font-weight:bold;color:#74531f;">Post</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">IsAssignableFrom</span>&lt;<span style="color:#2b91af;">OkResult</span>&gt;(<span style="font-weight:bold;color:#1f377f;">actual</span>); }</pre> </p> <p> This test reproduces the behaviour that was recorded in the above JSON log. While there was already one existing reservation (returned from <code>ReadReservations</code>), the system had enough remaining capacity to accept the new reservation. Therefore, the expected result is an <code>OkResult</code>. </p> <h3 id="2e246dfafa7e49c58600a066adf3ed0d"> Replay <a href="#2e246dfafa7e49c58600a066adf3ed0d" title="permalink">#</a> </h3> <p> You probably noticed the helper methods <code>Log.LoadFile</code> and <code>Log.LoadReservationsControllerPostScenario</code>. This API is just a prototype to get the point across. There's little to say about <code>LoadFile</code>, since it just reads the file. The <code>LoadReservationsControllerPostScenario</code> method performs the bulk of the work. It parses the JSON string into a collection of observations. It then feeds these observations to test-specific implementations of the dependencies required by <code>ReservationsController</code>. </p> <p> For example, here's the test-specific implementation of <code>IClock</code>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">ReplayClock</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IClock</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Queue</span>&lt;<span style="color:#2b91af;">DateTime</span>&gt;&nbsp;times; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">ReplayClock</span>(<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">DateTime</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">times</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.times&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Queue</span>&lt;<span style="color:#2b91af;">DateTime</span>&gt;(<span style="font-weight:bold;color:#1f377f;">times</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">DateTime</span>&nbsp;<span style="font-weight:bold;color:#74531f;">GetCurrentDateTime</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;times.<span style="font-weight:bold;color:#74531f;">Dequeue</span>(); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> The above JSON log example only contains a single observation of <code>GetCurrentDateTime</code>, but an arbitrary log may contain zero, one, or several observations. The idea is to replay them, starting with the earliest. <code>ReplayClock</code> just creates a <code>Queue</code> of them and <code>Dequeue</code> every time <code>GetCurrentDateTime</code> executes. </p> <p> The test-specific <code>ReplayReservationsRepository</code> class works the same way: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">ReplayReservationsRepository</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IReservationsRepository</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">IDictionary</span>&lt;<span style="color:#2b91af;">DateTime</span>,&nbsp;<span style="color:#2b91af;">Queue</span>&lt;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&gt;&gt;&nbsp;reads; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">ReplayReservationsRepository</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IDictionary</span>&lt;<span style="color:#2b91af;">DateTime</span>,&nbsp;<span style="color:#2b91af;">Queue</span>&lt;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&gt;&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">reads</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.reads&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">reads</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Create</span>(<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="font-weight:bold;color:#74531f;">ReadReservations</span>(<span style="color:#2b91af;">DateTime</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">date</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;reads[<span style="font-weight:bold;color:#1f377f;">date</span>].<span style="font-weight:bold;color:#74531f;">Dequeue</span>(); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> You'll notice that in order to implement <code>ReadReservations</code>, the <code>ReplayReservationsRepository</code> class needs a dictionary of queues. The <code>ReplayClock</code> class didn't need a dictionary, because <code>GetCurrentDateTime</code> takes no input. The <code>ReadReservations</code> method, on the other hand, takes a <code>date</code> as a method argument. You might have observations of <code>ReadReservations</code> for different dates, and multiple observations for each date. That's the reason that <code>ReplayReservationsRepository</code> needs a dictionary of queues. </p> <p> The <code>Create</code> method doesn't return anything, so I decided that this methods should do nothing. </p> <p> The <code>LoadReservationsControllerPostScenario</code> function parses the JSON log and creates instances of these <a href="https://en.wikipedia.org/wiki/Test_double">Test Doubles</a>. </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">repository</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ReplayReservationsRepository</span>(<span style="font-weight:bold;color:#1f377f;">reads</span>); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">clock</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ReplayClock</span>(<span style="font-weight:bold;color:#1f377f;">times</span>); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">controller</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ReservationsController</span>(<span style="font-weight:bold;color:#1f377f;">seatingDuration</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">tables</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">repository</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">clock</span>);</pre> </p> <p> And that, together with the parsed HTTP input, is what <code>LoadReservationsControllerPostScenario</code> returns: </p> <p> <pre><span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">controller</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>);</pre> </p> <p> This is only a prototype to illustrate the point that you can reproduce an interaction if you have all the impure inputs and outputs. The details are available in the source code repository. </p> <h3 id="cde93455d7354c3bb99b4e6fbb1b4792"> Summary <a href="#cde93455d7354c3bb99b4e6fbb1b4792" title="permalink">#</a> </h3> <p> This article demonstrated how making the distinction between pure and impure code is useful in many situations. For logging purposes, you only need to log the impure inputs and outputs. That's neither too little logging, nor too much, but just right: <em>Goldilogs</em>. </p> <p> Model any (potentially) impure interaction as a dependency and use Dependency Injection. This enables you to reproduce observed behaviour from logs. Don't inject logging services into your Controllers or Domain Models. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Repeatable execution in Haskell https://blog.ploeh.dk/2020/03/30/repeatable-execution-in-haskell 2020-03-30T08:02:00+00:00 Mark Seemann <div id="post"> <p> <em>A way to figure out what to log, and what not to log, using Haskell.</em> </p> <p> This article is part of <a href="/2020/03/23/repeatable-execution">a series of articles about repeatable execution</a>. The previous article argued that if you've logged the impure actions that a system made, you have enough information to reproduce what happened. </p> <p> In most languages, <a href="/2020/02/24/discerning-and-maintaining-purity">it's difficult to discriminate between pure functions and impure actions</a>, but <a href="https://www.haskell.org">Haskell</a> explicitly makes that distinction. I often use it for proof of concepts for that reason. I'll do that here as well. </p> <p> This proof of concept is mostly to verify what a decade of functional programming has already taught me. For the functionality that the previous article introduced, the impure actions involve a database and the system clock. </p> <p> The code shown in this article is <a href="https://github.com/ploeh/reservation-api-slice-haskell">available on GitHub</a>. </p> <h3 id="1c5f6ac50111450c8cf9b6d064977bcc"> Pure interactions <a href="#1c5f6ac50111450c8cf9b6d064977bcc" title="permalink">#</a> </h3> <p> I'll use <a href="/2017/07/10/pure-interactions">free monads to model impure interactions as pure functions</a>. For this particular example code base, an <a href="/2020/03/02/impureim-sandwich">impureim sandwich</a> would have been sufficient. I do, however, get the impression that many readers find it hard to extrapolate from impureim sandwiches to a general architecture. For the benefit of those readers, the example uses free monads. </p> <p> The system clock interaction is the simplest: </p> <p> <pre><span style="color:blue;">newtype</span>&nbsp;ClockInstruction&nbsp;next&nbsp;=&nbsp;CurrentTime&nbsp;(LocalTime&nbsp;-&gt;&nbsp;next)&nbsp;<span style="color:blue;">deriving</span>&nbsp;Functor</pre> </p> <p> There's only one instruction. It takes no input, but returns the current time and date. </p> <p> For database interactions, I went through a few iterations and arrived at this set of instructions: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;ReservationsInstruction&nbsp;next&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;ReadReservation&nbsp;UUID&nbsp;(Maybe&nbsp;Reservation&nbsp;-&gt;&nbsp;next) &nbsp;&nbsp;|&nbsp;ReadReservations&nbsp;LocalTime&nbsp;([Reservation]&nbsp;-&gt;&nbsp;next) &nbsp;&nbsp;|&nbsp;CreateReservation&nbsp;Reservation&nbsp;next &nbsp;&nbsp;<span style="color:blue;">deriving</span>&nbsp;Functor</pre> </p> <p> There's two queries and a command. The intent with the <code>CreateReservation</code> command is to create a new reservation row in the database. The two queries fetch a single reservation based on ID, or a set of reservations based on a date. A central type for this instruction set is <code>Reservation</code>: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;Reservation&nbsp;=&nbsp;Reservation &nbsp;&nbsp;{&nbsp;reservationId&nbsp;::&nbsp;UUID &nbsp;&nbsp;,&nbsp;reservationDate&nbsp;::&nbsp;LocalTime &nbsp;&nbsp;,&nbsp;reservationName&nbsp;::&nbsp;String &nbsp;&nbsp;,&nbsp;reservationEmail&nbsp;::&nbsp;String &nbsp;&nbsp;,&nbsp;reservationQuantity&nbsp;::&nbsp;Int &nbsp;&nbsp;}&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#2b91af;">Eq</span>,&nbsp;<span style="color:#2b91af;">Show</span>,&nbsp;<span style="color:#2b91af;">Read</span>,&nbsp;<span style="color:#2b91af;">Generic</span>)</pre> </p> <p> The program has to interact both with the system clock and the database, so ultimately it turned out to be useful to combine these two instruction sets into one: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;ReservationsProgram&nbsp;=&nbsp;Free&nbsp;(Sum&nbsp;ReservationsInstruction&nbsp;ClockInstruction)</pre> </p> <p> I used the <code>Sum</code> functor to combine the two instruction sets, and then turned them into a <code>Free</code> monad. </p> <p> With free monads, I find that my code becomes more readable if I define helper functions for each instruction: </p> <p> <pre><span style="color:#2b91af;">readReservation</span>&nbsp;::&nbsp;<span style="color:blue;">UUID</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsProgram</span>&nbsp;(<span style="color:#2b91af;">Maybe</span>&nbsp;<span style="color:blue;">Reservation</span>) readReservation&nbsp;rid&nbsp;=&nbsp;liftF&nbsp;$&nbsp;InL&nbsp;$&nbsp;ReadReservation&nbsp;rid&nbsp;<span style="color:blue;">id</span> <span style="color:#2b91af;">readReservations</span>&nbsp;::&nbsp;<span style="color:blue;">LocalTime</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsProgram</span>&nbsp;[<span style="color:blue;">Reservation</span>] readReservations&nbsp;t&nbsp;=&nbsp;liftF&nbsp;$&nbsp;InL&nbsp;$&nbsp;ReadReservations&nbsp;t&nbsp;<span style="color:blue;">id</span> <span style="color:#2b91af;">createReservation</span>&nbsp;::&nbsp;<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsProgram</span>&nbsp;() createReservation&nbsp;r&nbsp;=&nbsp;liftF&nbsp;$&nbsp;InL&nbsp;$&nbsp;CreateReservation&nbsp;r&nbsp;<span style="color:blue;">()</span> <span style="color:#2b91af;">currentTime</span>&nbsp;::&nbsp;<span style="color:blue;">ReservationsProgram</span>&nbsp;<span style="color:blue;">LocalTime</span> currentTime&nbsp;=&nbsp;liftF&nbsp;$&nbsp;InR&nbsp;$&nbsp;CurrentTime&nbsp;<span style="color:blue;">id</span></pre> </p> <p> There's much else going on in the code base, but that's how I model feature-specific impure actions. </p> <h3 id="46812b6dc4594937b0697ca09134af83"> Receive a reservation <a href="#46812b6dc4594937b0697ca09134af83" title="permalink">#</a> </h3> <p> The central feature of the service is to receive and handle an HTTP POST request, as described in the introductory article. When a document arrives it triggers a series of non-trivial work: <ol> <li>The service validates the input data. Among other things, it checks that the reservation is in the future. It uses <code>currentTime</code> for this.</li> <li>It queries the database for existing reservations. It uses <code>readReservations</code> for this.</li> <li>It uses complex business logic to determine whether to accept the reservation. This essentially implements the <a href="/2020/01/27/the-maitre-d-kata">Ma&icirc;tre d' kata</a>.</li> <li>If it accepts the reservation, it stores it. It uses <code>createReservation</code> for this.</li> </ol> These steps manifest as this function: </p> <p> <pre><span style="color:#2b91af;">tryAccept</span>&nbsp;::&nbsp;<span style="color:blue;">NominalDiffTime</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;[<span style="color:blue;">Table</span>] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ExceptT</span>&nbsp;(<span style="color:blue;">APIError</span>&nbsp;<span style="color:blue;">ByteString</span>)&nbsp;<span style="color:blue;">ReservationsProgram</span>&nbsp;() tryAccept&nbsp;seatingDuration&nbsp;tables&nbsp;r&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;now&nbsp;&lt;-&nbsp;lift&nbsp;currentTime &nbsp;&nbsp;_&nbsp;&lt;-&nbsp;liftEither&nbsp;$&nbsp;validateReservation&nbsp;now&nbsp;r &nbsp;&nbsp;reservations&nbsp;&lt;- &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">fmap</span>&nbsp;(removeNonOverlappingReservations&nbsp;seatingDuration&nbsp;r)&nbsp;&lt;$&gt; &nbsp;&nbsp;&nbsp;&nbsp;lift&nbsp;$&nbsp;readReservations&nbsp;$&nbsp;reservationDate&nbsp;r &nbsp;&nbsp;_&nbsp;&lt;-&nbsp;liftEither&nbsp;$&nbsp;canAccommodateReservation&nbsp;tables&nbsp;reservations&nbsp;r &nbsp;&nbsp;lift&nbsp;$&nbsp;createReservation&nbsp;r</pre> </p> <p> If you're interested in details, the code is available on GitHub. I may later write other articles about interesting details. </p> <p> In the context of repeatable execution and logging, the key is that this is a <a href="https://en.wikipedia.org/wiki/Pure_function">pure function</a>. It does, however, return a <code>ReservationsProgram</code> (free monad), so it's not going to <em>do</em> anything until interpreted. The interpreters are impure, so this is where logging has to take place. </p> <h3 id="3cc3141ffcc644c78618f117c53f66ba"> HTTP API <a href="#3cc3141ffcc644c78618f117c53f66ba" title="permalink">#</a> </h3> <p> The above <code>tryAccept</code> function is decoupled from boundary concerns. It has little HTTP-specific functionality. </p> <p> I've written the actual HTTP API using <a href="https://www.servant.dev">Servant</a>. The following function translates the above Domain Model to an HTTP API: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;ReservationsProgramT&nbsp;=&nbsp;FreeT&nbsp;(Sum&nbsp;ReservationsInstruction&nbsp;ClockInstruction) <span style="color:#2b91af;">reservationServer</span>&nbsp;::&nbsp;<span style="color:blue;">NominalDiffTime</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;[<span style="color:blue;">Table</span>] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ServerT</span>&nbsp;<span style="color:blue;">ReservationAPI</span>&nbsp;(<span style="color:blue;">ReservationsProgramT</span>&nbsp;<span style="color:blue;">Handler</span>) reservationServer&nbsp;seatingDuration&nbsp;tables&nbsp;=&nbsp;getReservation&nbsp;:&lt;|&gt;&nbsp;postReservation &nbsp;&nbsp;<span style="color:blue;">where</span> &nbsp;&nbsp;&nbsp;&nbsp;getReservation&nbsp;rid&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;mr&nbsp;&lt;-&nbsp;toFreeT&nbsp;$&nbsp;readReservation&nbsp;rid &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;mr&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Just&nbsp;r&nbsp;-&gt;&nbsp;<span style="color:blue;">return</span>&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Nothing&nbsp;-&gt;&nbsp;throwError&nbsp;err404 &nbsp;&nbsp;&nbsp;&nbsp;postReservation&nbsp;r&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;e&nbsp;&lt;-&nbsp;toFreeT&nbsp;$&nbsp;runExceptT&nbsp;$&nbsp;tryAccept&nbsp;seatingDuration&nbsp;tables&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;e&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Right&nbsp;<span style="color:blue;">()</span>&nbsp;-&gt;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">()</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Left&nbsp;(ValidationError&nbsp;err)&nbsp;-&gt;&nbsp;throwError&nbsp;$&nbsp;err400&nbsp;{&nbsp;errBody&nbsp;=&nbsp;err&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Left&nbsp;&nbsp;(ExecutionError&nbsp;err)&nbsp;-&gt;&nbsp;throwError&nbsp;$&nbsp;err500&nbsp;{&nbsp;errBody&nbsp;=&nbsp;err&nbsp;}</pre> </p> <p> This API also exposes a reservation as a resource you can query with a <code>GET</code> request, but I'm not going to comment much on that. It uses the above <code>readReservation</code> helper function, but there's little logic involved in the implementation. </p> <p> The above <code>reservationServer</code> function implements, by the way, only a <em>partial</em> API. It defines the <code>/reservations</code> resource, as explained in the overview article. Its type is defined as: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;ReservationAPI&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Capture&nbsp;<span style="color:#a31515;">&quot;reservationId&quot;</span>&nbsp;UUID&nbsp;:&gt;&nbsp;Get&nbsp;&#39;[JSON]&nbsp;Reservation &nbsp;&nbsp;:&lt;|&gt;&nbsp;ReqBody&nbsp;&#39;[JSON]&nbsp;Reservation&nbsp;:&gt;&nbsp;Post&nbsp;&#39;[JSON]&nbsp;<span style="color:blue;">()</span></pre> </p> <p> That's just one resource. <em>Servant</em> enables you define many resources and combine them into a larger API. For this example, the <code>/reservations</code> resource is all there is, so I define the entire API like this: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;API&nbsp;=&nbsp;<span style="color:#a31515;">&quot;reservations&quot;</span>&nbsp;:&gt;&nbsp;ReservationAPI</pre> </p> <p> You can also define your complete <code>server</code> from several partial services, but in this example, I only have one: </p> <p> <pre>server&nbsp;=&nbsp;reservationServer</pre> </p> <p> Had I had more resources, I could have combined several values with a combinator, but now that I have only <code>reservationServer</code> it seems redundant, I admit. </p> <h3 id="678638fe747f41c491994dc43be49d7b"> Hosting the API <a href="#678638fe747f41c491994dc43be49d7b" title="permalink">#</a> </h3> <p> The <code>reservationServer</code> function, and thereby also <code>server</code>, returns a <code>ServerT</code> value. <em>Servant</em> ultimately demands a <code>Server</code> value to <code>serve</code> it. We need to transform the <code>ServerT</code> value into a <code>Server</code> value, which we can do with <code>hoistServer</code>: </p> <p> <pre><span style="color:#2b91af;">runApp</span>&nbsp;::&nbsp;<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">Int</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;() runApp&nbsp;connStr&nbsp;port&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;<span style="color:blue;">putStrLn</span>&nbsp;$&nbsp;<span style="color:#a31515;">&quot;Starting&nbsp;server&nbsp;on&nbsp;port&nbsp;&quot;</span>&nbsp;++&nbsp;<span style="color:blue;">show</span>&nbsp;port&nbsp;++&nbsp;<span style="color:#a31515;">&quot;.&quot;</span> &nbsp;&nbsp;<span style="color:blue;">putStrLn</span>&nbsp;<span style="color:#a31515;">&quot;Press&nbsp;Ctrl&nbsp;+&nbsp;C&nbsp;to&nbsp;stop&nbsp;the&nbsp;server.&quot;</span> &nbsp;&nbsp;ls&nbsp;&lt;-&nbsp;loggerSet &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;logLn&nbsp;s&nbsp;=&nbsp;pushLogStrLn&nbsp;ls&nbsp;$&nbsp;toLogStr&nbsp;s &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;hoistSQL&nbsp;=&nbsp;hoistServer&nbsp;api&nbsp;$&nbsp;runInSQLServerAndOnSystemClock&nbsp;logLn&nbsp;$&nbsp;pack&nbsp;connStr &nbsp;&nbsp;(seatingDuration,&nbsp;tables)&nbsp;&lt;-&nbsp;readConfig &nbsp;&nbsp;logHttp&nbsp;&lt;-&nbsp;logHttpMiddleware&nbsp;ls &nbsp;&nbsp;run&nbsp;port&nbsp;$&nbsp;logHttp&nbsp;$&nbsp;serve&nbsp;api&nbsp;$&nbsp;hoistSQL&nbsp;$&nbsp;server&nbsp;seatingDuration&nbsp;tables</pre> </p> <p> The <code>hoistServer</code> function enables you to translate a <code>ServerT api m</code> into a <code>ServerT api n</code> value. Since <code>Server</code> is a type alias for <code>ServerT api Handler</code>, we need to translate the complicated monad returned from <code>server</code> into a <code>Handler</code>. The <code>runInSQLServerAndOnSystemClock</code> function does most of the heavy lifting. </p> <p> You'll also notice that the <code>runApp</code> function configures some logging. Apart from some HTTP-level middleware, the <code>logLn</code> function logs a line to a text file. The <code>runApp</code> function passes it as an argument to the <code>runInSQLServerAndOnSystemClock</code> function. We'll return to logging later in this article, but first I find it instructive to outline what happens in <code>runInSQLServerAndOnSystemClock</code>. </p> <p> As the name implies, two major actions take place. The function interprets database interactions by executing impure actions against SQL Server. It also interprets clock interactions by querying the system clock. </p> <h3 id="05b701cca27f44479c4c3bc1d169d935"> Using the system clock <a href="#05b701cca27f44479c4c3bc1d169d935" title="permalink">#</a> </h3> <p> The system-clock-based interpreter is the simplest of the two interpreters. It interprets <code>ClockInstruction</code> values by querying the system clock for the current time: </p> <p> <pre><span style="color:#2b91af;">runOnSystemClock</span>&nbsp;::&nbsp;<span style="color:blue;">MonadIO</span>&nbsp;m&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;<span style="color:blue;">ClockInstruction</span>&nbsp;(m&nbsp;a)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a runOnSystemClock&nbsp;(CurrentTime&nbsp;next)&nbsp;=&nbsp;liftIO&nbsp;(zonedTimeToLocalTime&nbsp;&lt;$&gt;&nbsp;getZonedTime)&nbsp;&gt;&gt;=&nbsp;next</pre> </p> <p> This function translates a <code>ClockInstruction (m a)</code> to an <code>m a</code> value by executing the impure <code>getZonedTime</code> function. From the returned <code>ZonedTime</code> value, it then extracts the local time, which it passes to <code>next</code>. </p> <p> You may have two questions: <ul> <li>Why map <code>ClockInstruction (m a)</code> instead of <code>ClockInstruction a</code>?</li> <li>Why <code>MonadIO</code>?</li> </ul> I'll address each in turn. </p> <p> My ultimate goal with each of these interpreters is to compose them into <code>runInSQLServerAndOnSystemClock</code>. As described above, this function transforms <code>ServerT API (ReservationsProgramT Handler)</code> into a <code>ServerT API Handler</code> (also known as <code>Server API</code>). Another way to put this is that we need to collapse <code>ReservationsProgramT Handler</code> to <code>Handler</code> by, so to speak, removing <code>ReservationsProgramT</code>. </p> <p> Recall that a type like <code>ReservationsProgramT Handler</code> is really in 'curried' form. This is actually the parametrically polymorphic type <code>ReservationsProgramT Handler a</code>. Likewise, <code>Handler</code> is also parametrically polymorphic: <code>Handler a</code>. What we need, then, is a function with the type <code>ReservationsProgramT Handler a -&gt; Handler a</code> or, more generally, <code>FreeT f m a -&gt; m a</code>. This follows because <code>ReservationsProgramT</code> is an alias for <code>FreeT ...</code>, and <code>Handler</code> is <a href="https://bartoszmilewski.com/2014/01/14/functors-are-containers">a container</a> of <code>a</code> values. </p> <p> There's a function for that in <a href="http://hackage.haskell.org/package/free/docs/Control-Monad-Trans-Free.html">Control.Monad.Trans.Free</a> called <code>iterT</code>: </p> <p> <pre><span style="color:#2b91af;">iterT</span>&nbsp;::&nbsp;(<span style="color:blue;">Functor</span>&nbsp;f,&nbsp;<span style="color:blue;">Monad</span>&nbsp;m)&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;(f&nbsp;(m&nbsp;a)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">FreeT</span>&nbsp;f&nbsp;m&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a</pre> </p> <p> This fits our need. For each of the functors in <code>ReservationsProgramT</code>, then, we need a function <code>f (m a) -&gt; m a</code>. Specifically, for <code>ClockInstruction</code>, we need to define a function with the type <code>ClockInstruction (Handler a) -&gt; Handler a</code>. Consider, however, the definition of <code>Handler</code>. It's a <code>newtype</code> over a <code>newtype</code>, so much wrapping is required. If I specifically wanted to return that explicit type, I'd have to take the <code>IO</code> vale produced by <code>getZonedTime</code> and wrap it in <code>Handler</code>, which would require me to first wrap it in <code>ExceptT</code>, which again would require me to wrap it in <code>Either</code>. That's a lot of bother, but <code>Handler</code> is also a <code>MonadIO</code> instance, and that elegantly sidesteps the issue. By implementing <code>runOnSystemClock</code> with <code>liftIO</code>, it works for all <code>MonadIO</code> instances, including <code>Handler</code>. </p> <p> Hopefully, that explains why <code>runOnSystemClock</code> has the type that it has. </p> <h3 id="9f530f57c49549b6823c45859ee5890c"> Using the database <a href="#9f530f57c49549b6823c45859ee5890c" title="permalink">#</a> </h3> <p> The database interpreter is more complex than <code>runOnSystemClock</code>, but it follows the same principles. The reasoning outlined above also apply here. </p> <p> <pre><span style="color:#2b91af;">runInSQLServer</span>&nbsp;::&nbsp;<span style="color:blue;">MonadIO</span>&nbsp;m&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;<span style="color:blue;">Text</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsInstruction</span>&nbsp;(m&nbsp;a)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a runInSQLServer&nbsp;connStr&nbsp;(ReadReservation&nbsp;rid&nbsp;next)&nbsp;= &nbsp;&nbsp;liftIO&nbsp;(readReservation&nbsp;connStr&nbsp;rid)&nbsp;&gt;&gt;=&nbsp;next runInSQLServer&nbsp;connStr&nbsp;(ReadReservations&nbsp;t&nbsp;next)&nbsp;= &nbsp;&nbsp;liftIO&nbsp;(readReservations&nbsp;connStr&nbsp;t)&nbsp;&gt;&gt;=&nbsp;next runInSQLServer&nbsp;connStr&nbsp;(CreateReservation&nbsp;r&nbsp;next)&nbsp;= &nbsp;&nbsp;liftIO&nbsp;(insertReservation&nbsp;connStr&nbsp;r)&nbsp;&gt;&gt;&nbsp;next</pre> </p> <p> Since <code>ReservationsInstruction</code> is a sum type with three cases, the <code>runInSQLServer</code> action has to handle all three. Each case calls a dedicated helper function. I'll only show one of these to give you a sense for how they look. </p> <p> <pre><span style="color:#2b91af;">readReservations</span>&nbsp;::&nbsp;<span style="color:blue;">Text</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">LocalTime</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;[<span style="color:blue;">Reservation</span>] readReservations&nbsp;connStr&nbsp;(LocalTime&nbsp;d&nbsp;_)&nbsp;= &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;sql&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;SELECT&nbsp;[Guid],&nbsp;[Date],&nbsp;[Name],&nbsp;[Email],&nbsp;[Quantity]\ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\FROM&nbsp;[dbo].[Reservations]\ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\WHERE&nbsp;CONVERT(DATE,&nbsp;[Date])&nbsp;=&nbsp;&quot;</span>&nbsp;&lt;&gt;&nbsp;toSql&nbsp;d &nbsp;&nbsp;<span style="color:blue;">in</span>&nbsp;withConnection&nbsp;connStr&nbsp;$&nbsp;\conn&nbsp;-&gt;&nbsp;<span style="color:blue;">fmap</span>&nbsp;unDbReservation&nbsp;&lt;$&gt;&nbsp;query&nbsp;conn&nbsp;sql</pre> </p> <p> You can see all the details about <code>withConnection</code>, <code>unDbReservation</code>, etcetera in the Git repository. The principal point is that these are just normal <code>IO</code> actions. </p> <h3 id="7dd30abf99b24ec6b13a1c22d0f6f150"> Basic composition <a href="#7dd30abf99b24ec6b13a1c22d0f6f150" title="permalink">#</a> </h3> <p> The two interpreters are all we need to compose a working system: </p> <p> <pre><span style="color:#2b91af;">runInSQLServerAndOnSystemClock</span>&nbsp;::&nbsp;<span style="color:blue;">MonadIO</span>&nbsp;m&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;<span style="color:blue;">Text</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsProgramT</span>&nbsp;m&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a runInSQLServerAndOnSystemClock&nbsp;connStr&nbsp;=&nbsp;iterT&nbsp;go &nbsp;&nbsp;<span style="color:blue;">where</span>&nbsp;go&nbsp;(InL&nbsp;rins)&nbsp;=&nbsp;DB.runInSQLServer&nbsp;connStr&nbsp;rins &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;go&nbsp;(InR&nbsp;cins)&nbsp;=&nbsp;runOnSystemClock&nbsp;cins</pre> </p> <p> The <code>iterT</code> function enables you to interpret a <code>FreeT</code> value, of which <code>ReservationsProgramT</code> is an alias. The <code>go</code> function just pattern-matches on the two cases of the <code>Sum</code> functor, and delegates to the corresponding interpreter. </p> <p> This composition enables the system to run and do the intended work. You can start the server and make <code>GET</code> and <code>POST</code> requests against the <code>/reservations</code> resource, as outlined in the first article in this small series. </p> <p> This verifies what I already hypothesized. This feature set requires two distinct sets of impure interactions: <ul> <li>Getting the current time</li> <li>Querying and writing to a database</li> </ul> Once you've worked with Haskell for some time, you'll get good at predicting which actions are impure, and which functionality can be kept pure. The current result isn't surprising. </p> <p> It does make it clear what ought to be logged. All the pure functionality can be reproduced if you have the inputs. You only need to log the impure interactions, and now you know what they are. </p> <h3 id="f29d957fcfe644e9a9efaf70bf58ad74"> Compose with logging <a href="#f29d957fcfe644e9a9efaf70bf58ad74" title="permalink">#</a> </h3> <p> You need to log the impure operations, and you know that they're interacting with the system clock and the database. As usual, starting with the system clock is most accessible. You can write what's essentially a <a href="https://en.wikipedia.org/wiki/Decorator_pattern">Decorator</a> of any <code>ClockInstruction</code> interpreter: </p> <p> <pre><span style="color:#2b91af;">logClock</span>&nbsp;::&nbsp;<span style="color:blue;">MonadIO</span>&nbsp;m &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;(<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;(forall&nbsp;x.&nbsp;<span style="color:blue;">ClockInstruction</span>&nbsp;(m&nbsp;x)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;x) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ClockInstruction</span>&nbsp;(m&nbsp;a)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a logClock&nbsp;logLn&nbsp;inner&nbsp;(CurrentTime&nbsp;next)&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;output&nbsp;&lt;-&nbsp;inner&nbsp;$&nbsp;CurrentTime&nbsp;<span style="color:blue;">return</span> &nbsp;&nbsp;liftIO&nbsp;$&nbsp;writeLogEntry&nbsp;logLn&nbsp;<span style="color:#a31515;">&quot;CurrentTime&quot;</span>&nbsp;<span style="color:blue;">()</span>&nbsp;output &nbsp;&nbsp;next&nbsp;output</pre> </p> <p> The <code>logClock</code> action decorates any <code>inner</code> interpreter with the logging action <code>logLn</code>. It returns an action of the same type as it decorates. </p> <p> It relies on a helper function called <code>writeLogEntry</code>, which handles some of the formalities of formatting and time-stamping each log entry. </p> <p> You can decorate any database interpreter in the same way: </p> <p> <pre><span style="color:#2b91af;">logReservations</span>&nbsp;::&nbsp;<span style="color:blue;">MonadIO</span>&nbsp;m &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;(<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;(forall&nbsp;x.&nbsp;<span style="color:blue;">ReservationsInstruction</span>&nbsp;(m&nbsp;x)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;x) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsInstruction</span>&nbsp;(m&nbsp;a)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a logReservations&nbsp;logLn&nbsp;inner&nbsp;(ReadReservation&nbsp;rid&nbsp;next)&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;output&nbsp;&lt;-&nbsp;inner&nbsp;$&nbsp;ReadReservation&nbsp;rid&nbsp;<span style="color:blue;">return</span> &nbsp;&nbsp;liftIO&nbsp;$&nbsp;writeLogEntry&nbsp;logLn&nbsp;<span style="color:#a31515;">&quot;ReadReservation&quot;</span>&nbsp;rid&nbsp;output &nbsp;&nbsp;next&nbsp;output logReservations&nbsp;logLn&nbsp;inner&nbsp;(ReadReservations&nbsp;t&nbsp;next)&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;output&nbsp;&lt;-&nbsp;inner&nbsp;$&nbsp;ReadReservations&nbsp;t&nbsp;<span style="color:blue;">return</span> &nbsp;&nbsp;liftIO&nbsp;$&nbsp;writeLogEntry&nbsp;logLn&nbsp;<span style="color:#a31515;">&quot;ReadReservations&quot;</span>&nbsp;t&nbsp;output &nbsp;&nbsp;next&nbsp;output logReservations&nbsp;logLn&nbsp;inner&nbsp;(CreateReservation&nbsp;r&nbsp;next)&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;output&nbsp;&lt;-&nbsp;inner&nbsp;$&nbsp;CreateReservation&nbsp;r&nbsp;(<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">()</span>) &nbsp;&nbsp;liftIO&nbsp;$&nbsp;writeLogEntry&nbsp;logLn&nbsp;<span style="color:#a31515;">&quot;CreateReservation&quot;</span>&nbsp;r&nbsp;output &nbsp;&nbsp;next</pre> </p> <p> The <code>logReservations</code> action follows the same template as <code>logClock</code>; only it has more lines of code because <code>ReservationsInstruction</code> is a discriminated union with three cases. </p> <p> With these Decorator actions you can change the application composition so that it logs all impure inputs and outputs: </p> <p> <pre><span style="color:#2b91af;">runInSQLServerAndOnSystemClock</span>&nbsp;::&nbsp;<span style="color:blue;">MonadIO</span>&nbsp;m &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;(<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Text</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsProgramT</span>&nbsp;m&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a runInSQLServerAndOnSystemClock&nbsp;logLn&nbsp;connStr&nbsp;=&nbsp;iterT&nbsp;go &nbsp;&nbsp;<span style="color:blue;">where</span>&nbsp;go&nbsp;(InL&nbsp;rins)&nbsp;=&nbsp;logReservations&nbsp;logLn&nbsp;(DB.runInSQLServer&nbsp;connStr)&nbsp;rins &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;go&nbsp;(InR&nbsp;cins)&nbsp;=&nbsp;logClock&nbsp;logLn&nbsp;runOnSystemClock&nbsp;cins</pre> </p> <p> This not only implements the desired functionality, but also <em>Goldilogs:</em> not too little, not too much, but just what you need. Notice that I didn't have to change any of my Domain Model or HTTP-specific code to enable logging. This cross-cutting concern is enabled entirely via composition. </p> <h3 id="3d37879949774c10a002ad7ff93ad571"> Repeatability <a href="#3d37879949774c10a002ad7ff93ad571" title="permalink">#</a> </h3> <p> An HTTP request like this: </p> <p> <pre>POST /reservations/ HTTP/1.1 Content-Type: application/json { &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;id&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;c3cbfbc7-6d64-4ead-84ef-7f89de5b7e1c&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;date&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2020-03-20&nbsp;19:00:00&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;name&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;Elissa&nbsp;Megan&nbsp;Powers&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;email&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;emp@example.com&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;quantity&quot;</span>:&nbsp;3 }</pre> </p> <p> produces a series of log entries like these: </p> <p> <pre>LogEntry {logTime = 2019-12-29 20:21:53.0029235 UTC, logOperation = "CurrentTime", logInput = "()", logOutput = "2019-12-29 21:21:53.0029235"} LogEntry {logTime = 2019-12-29 20:21:54.0532677 UTC, logOperation = "ReadReservations", logInput = "2020-03-20 19:00:00", logOutput = "[]"} LogEntry {logTime = 2019-12-29 20:21:54.0809254 UTC, logOperation = "CreateReservation", logInput = "Reservation {reservationId = c3cbfbc7-6d64-4ead-84ef-7f89de5b7e1c, reservationDate = 2020-03-20 19:00:00, reservationName = \"Elissa Megan Powers\", reservationEmail = \"emp@example.com\", reservationQuantity = 3}", logOutput = "()"} LogEntry {logTime = 2019-12-29 20:21:54 UTC, logOperation = "PostReservation", logInput = "\"{ \\\"id\\\": \\\"c3cbfbc7-6d64-4ead-84ef-7f89de5b7e1c\\\", \\\"date\\\": \\\"2020-03-20 19:00:00\\\", \\\"name\\\": \\\"Elissa Megan Powers\\\", \\\"email\\\": \\\"emp@example.com\\\", \\\"quantity\\\": 3 }\"", logOutput = "()"}</pre> </p> <p> This is only a prototype to demonstrate what's possible. In an attempt to make things simple for myself, I decided to just log data by using the <code>Show</code> instance of each value being logged. In order to reproduce behaviour, I'll rely on the corresponding <code>Read</code> instance for the type. This was probably naive, and not a decision I would employ in a production system, but it's good enough for a prototype. </p> <p> For example, the above log entry states that the <code>CurrentTime</code> instruction was evaluated and that the output was <code>2019-12-29 21:21:53.0029235</code>. Second, the <code>ReadReservations</code> instruction was evaluated with the input <code>2020-03-20 19:00:00</code> and the output was the empty list (<code>[]</code>). The third line records that the <code>CreateReservation</code> instruction was evaluated with a particular input, and that the output was <code>()</code>. </p> <p> The fourth and final record is the the actual values observed at the HTTP boundary. </p> <p> You can load and parse the logged data into a unit test or an interactive session: </p> <p> <pre>λ&gt; l &lt;- lines &lt;$&gt; readFile "the/path/to/the/log.txt" λ&gt; replayData = readReplayData l λ&gt; replayData ReplayData { &nbsp;&nbsp;observationsOfPostReservation = &nbsp;&nbsp;&nbsp;&nbsp;[Reservation { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservationId = c3cbfbc7-6d64-4ead-84ef-7f89de5b7e1c, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservationDate = 2020-03-20 19:00:00, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservationName = "Elissa Megan Powers", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservationEmail = "emp@example.com", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservationQuantity = 3}], &nbsp;&nbsp;observationsOfRead = fromList [], &nbsp;&nbsp;observationsOfReads = fromList [(2020-03-20 19:00:00,[[]])], &nbsp;&nbsp;observationsOfCurrentTime = [2019-12-29 21:21:53.0029235]} λ&gt; r = head $ observationsOfPostReservation replayData λ&gt; r Reservation { &nbsp;&nbsp;reservationId = c3cbfbc7-6d64-4ead-84ef-7f89de5b7e1c, &nbsp;&nbsp;reservationDate = 2020-03-20 19:00:00, &nbsp;&nbsp;reservationName = "Elissa Megan Powers", &nbsp;&nbsp;reservationEmail = "emp@example.com", &nbsp;&nbsp;reservationQuantity = 3}</pre> </p> <p> (I've added line breaks and indentation to some of the output to make it more readable, compared to what GHCi produces.) </p> <p> The most important thing to notice is the <code>readReplayData</code> function that parses the log file into Haskell data. I've also written a prototype of a function that can <code>replay</code> the actions as they happened: </p> <p> <pre>λ&gt; (seatingDuration, tables) &lt;- readConfig λ&gt; replay replayData $ tryAccept seatingDuration tables r Right ()</pre> </p> <p> The original HTTP request returned <code>200 OK</code> and that's exactly how <code>reservationServer</code> translates a <code>Right ()</code> result. So the above interaction is a faithful reproduction of what actually happened. </p> <h3 id="5d94afef4145456abe86ae6f2dd9445a"> Replay <a href="#5d94afef4145456abe86ae6f2dd9445a" title="permalink">#</a> </h3> <p> You may have noticed that I used a <code>replay</code> function above. This is only a prototype to get the point across. It's just another interpreter of <code>ReservationsProgram</code> (or, rather an <code>ExceptT</code> wrapper of <code>ReservationsProgram</code>): </p> <p> <pre><span style="color:#2b91af;">replay</span>&nbsp;::&nbsp;<span style="color:blue;">ReplayData</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ExceptT</span>&nbsp;e&nbsp;<span style="color:blue;">ReservationsProgram</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">Either</span>&nbsp;e&nbsp;a replay&nbsp;d&nbsp;=&nbsp;replayImp&nbsp;d&nbsp;.&nbsp;runExceptT &nbsp;&nbsp;<span style="color:blue;">where</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">replayImp</span>&nbsp;::&nbsp;<span style="color:blue;">ReplayData</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsProgram</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;a &nbsp;&nbsp;&nbsp;&nbsp;replayImp&nbsp;rd&nbsp;p&nbsp;=&nbsp;State.evalState&nbsp;(iterM&nbsp;go&nbsp;p)&nbsp;rd &nbsp;&nbsp;&nbsp;&nbsp;go&nbsp;(InL&nbsp;(ReadReservation&nbsp;rid&nbsp;next))&nbsp;=&nbsp;replayReadReservation&nbsp;rid&nbsp;&gt;&gt;=&nbsp;next &nbsp;&nbsp;&nbsp;&nbsp;go&nbsp;(InL&nbsp;(ReadReservations&nbsp;t&nbsp;next))&nbsp;=&nbsp;replayReadReservations&nbsp;t&nbsp;&gt;&gt;=&nbsp;next &nbsp;&nbsp;&nbsp;&nbsp;go&nbsp;(InL&nbsp;(CreateReservation&nbsp;_&nbsp;next))&nbsp;=&nbsp;next &nbsp;&nbsp;&nbsp;&nbsp;go&nbsp;(InR&nbsp;(CurrentTime&nbsp;next))&nbsp;=&nbsp;replayCurrentTime&nbsp;&gt;&gt;=&nbsp;next</pre> </p> <p> While this is compact Haskell code that <em>I</em> wrote, I still found it so abstruse that I decided to add a type annotation to a local function. It's not required, but I find that it helps me understand what <code>replayImp</code> does. It uses <code>iterM</code> (a cousin to <code>iterT</code>) to interpret the <code>ReservationsProgram</code>. The entire interpretation is stateful, so runs in the <code>State</code> monad. Here's an example: </p> <p> <pre><span style="color:#2b91af;">replayCurrentTime</span>&nbsp;::&nbsp;<span style="color:blue;">State</span>&nbsp;<span style="color:blue;">ReplayData</span>&nbsp;<span style="color:blue;">LocalTime</span> replayCurrentTime&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;xs&nbsp;&lt;-&nbsp;State.gets&nbsp;observationsOfCurrentTime &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;(observation:rest)&nbsp;=&nbsp;xs &nbsp;&nbsp;State.modify&nbsp;(\s&nbsp;-&gt;&nbsp;s&nbsp;{&nbsp;observationsOfCurrentTime&nbsp;=&nbsp;rest&nbsp;}) &nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;observation</pre> </p> <p> The <code>replayCurrentTime</code> function replays log observations of <code>CurrentTime</code> instructions. The <code>observationsOfCurrentTime</code> field is a list of observed values, parsed from a log. A <code>ReservationsProgram</code> might query the <code>CurrentTime</code> multiple times, so there could conceivably be several such observations. The idea is to replay them, starting with the earliest. </p> <p> Each time the function replays an observation, it should remove it from the log. It does that by first retrieving all observations from the state. It then pattern-matches the <code>observation</code> from the <code>rest</code> of the observations. I execute my code with the <code>-Wall</code> option, so I'm puzzled that I don't get a warning from the compiler about that line. After all, the <code>xs</code> list could be empty. This is, however, prototype code, so I decided to ignore that issue. </p> <p> Before the function returns the <code>observation</code> it updates the replay data by effectively removing the <code>observation</code>, but without touching anything else. </p> <p> The <code>replayReadReservation</code> and <code>replayReadReservations</code> functions follow the same template. You can consult the source code repository if you're curious about the details. You may also notice that the <code>go</code> function doesn't do anything when it encounters a <code>CreateReservation</code> instruction. This is because that instruction has no return value, so there's no reason to consult a log to figure out what to return. </p> <h3 id="fa5477f706a143d59c0006e52af2fe2d"> Summary <a href="#fa5477f706a143d59c0006e52af2fe2d" title="permalink">#</a> </h3> <p> The point of this article was to flesh out a fully functional feature (a vertical slice, if you're so inclined) in Haskell, in order to verify that the only impure actions involved are: <ul> <li>Getting the current time</li> <li>Interacting with the application database</li> </ul> This turns out to be the case. </p> <p> Furthermore, prototype code demonstrates that based on a log of impure interactions, you can repeat the logged execution. </p> <p> Now that we know what is impure and what can be pure, we can reproduce the same architecture in C# (or another mainstream programming language). </p> <p> <strong>Next:</strong> <a href="/2020/04/06/repeatable-execution-in-c">Repeatable execution in C#</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="4d71311250a54b1ca558a8469acdf545"> <div class="comment-author"><a href="https://majiehong.com/">Jiehong</a></div> <div class="comment-content"> <p>The Free Monad, as any monad, enforces sequential operations.</p> <p> How would you deal with having to sent multiple transactions (let's say to the db and via http), while also retrying <em>n</em> times if it fails? </p> </div> <div class="comment-date">2020-04-06 9:38 UTC</div> </div> <div class="comment" id="8f689c5cb98d42ad8e4d8eb02ef81cc3"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Jiehong, thank you for writing. I'm not sure that I can give you a complete answer, as this is something that I haven't experimented with in Haskell. </p> <p> In C#, on the other hand, you can implement stability patterns like <a href="https://en.wikipedia.org/wiki/Circuit_breaker_design_pattern">Circuit Breaker</a> and retries with <a href="https://en.wikipedia.org/wiki/Decorator_pattern">Decorators</a>. I don't see why you can't do that in Haskell as well. </p> </div> <div class="comment-date">2020-04-10 10:15 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Repeatable execution https://blog.ploeh.dk/2020/03/23/repeatable-execution 2020-03-23T08:17:00+00:00 Mark Seemann <div id="post"> <p> <em>What to log, and how to log it.</em> </p> <p> When I visit software organisations to help them make their code more maintainable, I often see code like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">ILog</span>&nbsp;Log&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} <span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">ActionResult</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Post</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>) { &nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Debug</span>(<span style="color:#a31515;">$&quot;Entering&nbsp;</span>{<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#74531f;">Post</span>)}<span style="color:#a31515;">&nbsp;method...&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:blue;">_</span>)) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Warning</span>(<span style="color:#a31515;">&quot;Invalid&nbsp;reservation&nbsp;date.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BadRequest</span>(<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Debug</span>(<span style="color:#a31515;">&quot;Mapping&nbsp;DTO&nbsp;to&nbsp;Domain&nbsp;Model.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Mapper</span>.<span style="color:#74531f;">Map</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date&nbsp;<span style="font-weight:bold;color:#74531f;">&lt;</span>&nbsp;<span style="color:#2b91af;">DateTime</span>.Now) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Warning</span>(<span style="color:#a31515;">&quot;Invalid&nbsp;reservation&nbsp;date.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BadRequest</span>(<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date}<span style="color:#a31515;">.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Debug</span>(<span style="color:#a31515;">&quot;Reading&nbsp;existing&nbsp;reservations&nbsp;from&nbsp;database.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservations</span>&nbsp;=&nbsp;Repository.<span style="font-weight:bold;color:#74531f;">ReadReservations</span>(<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">accepted</span>&nbsp;=&nbsp;maîtreD.<span style="font-weight:bold;color:#74531f;">CanAccept</span>(<span style="font-weight:bold;color:#1f377f;">reservations</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="font-weight:bold;color:#1f377f;">accepted</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Warning</span>(<span style="color:#a31515;">&quot;Not&nbsp;enough&nbsp;capacity&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">StatusCode</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">StatusCodes</span>.Status500InternalServerError, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;Couldn&#39;t&nbsp;accept.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Info</span>(<span style="color:#a31515;">&quot;Adding&nbsp;reservation&nbsp;to&nbsp;database.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;Repository.<span style="font-weight:bold;color:#74531f;">Create</span>(<span style="font-weight:bold;color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Debug</span>(<span style="color:#a31515;">$&quot;Leaving&nbsp;</span>{<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#74531f;">Post</span>)}<span style="color:#a31515;">&nbsp;method...&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Ok</span>(); }</pre> </p> <p> Logging like this annoys me. It adds avoidable noise to the code, making it harder to read, and thus, more difficult to maintain. </p> <h3 id="75930691088c44568c80941c70bc147a"> Ideal <a href="#75930691088c44568c80941c70bc147a" title="permalink">#</a> </h3> <p> The above code ought to look like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">ActionResult</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Post</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:blue;">_</span>)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BadRequest</span>(<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Mapper</span>.<span style="color:#74531f;">Map</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date&nbsp;<span style="font-weight:bold;color:#74531f;">&lt;</span>&nbsp;Clock.<span style="font-weight:bold;color:#74531f;">GetCurrentDateTime</span>()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BadRequest</span>(<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date}<span style="color:#a31515;">.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservations</span>&nbsp;=&nbsp;Repository.<span style="font-weight:bold;color:#74531f;">ReadReservations</span>(<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">accepted</span>&nbsp;=&nbsp;maîtreD.<span style="font-weight:bold;color:#74531f;">CanAccept</span>(<span style="font-weight:bold;color:#1f377f;">reservations</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="font-weight:bold;color:#1f377f;">accepted</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">StatusCode</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">StatusCodes</span>.Status500InternalServerError, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;Couldn&#39;t&nbsp;accept.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;Repository.<span style="font-weight:bold;color:#74531f;">Create</span>(<span style="font-weight:bold;color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Ok</span>(); }</pre> </p> <p> This is more readable. The logging statements are gone from the code, thereby amplifying the essential behaviour of the <code>Post</code> method. The noise is gone. </p> <p> <em>Wait a minute!</em> you might say, <em>You can't just remove logging! Logging is important.</em> </p> <p> Yes, I agree, and I didn't. This code still logs. It logs just what you need to log. No more, no less. </p> <h3 id="c176715622a74d69a312cfa8e47159fb"> Types of logging <a href="#c176715622a74d69a312cfa8e47159fb" title="permalink">#</a> </h3> <p> Before we talk about the technical details, I think it's important to establish some vocabulary and context. In this article, I use the term <em>logging</em> broadly to describe any sort of action of recording what happened while software executed. There's more than one reason an application might have to do that: <ul> <li> <strong>Instrumentation.</strong> You may log to support your own work. The first code listing in this article is a typical example of this style of logging. If you've ever had the responsibility of having to support an application that runs in production, you know that you need insight into what happens. When people report strange behaviours, you need those logs to support troubleshooting. </li> <li> <strong>Telemetry.</strong> You may log to support other people's work. You can write status updates, warnings, and errors to support operations. You can record Key Performance Indicators (KPIs) to support 'the business'. </li> <li> <strong>Auditing.</strong> You may log because you're legally obliged to do so. </li> <li> <strong>Metering.</strong> You may log who does what so that you can bill users based on consumption. </li> </ul> Regardless of motivation, I still consider these to be types of logging. All are <em>cross-cutting concerns</em> in that they're independent of application features. Logging records what happened, when it happened, who or what triggered the event, and so on. The difference between instrumentation, telemetry, auditing, and metering is only <em>what</em> you choose to persist. </p> <p> Particularly when it comes to instrumentation, I often see examples of 'overlogging'. When logging is done to support future troubleshooting, you can't predict what you're going to need, so it's better to log too much data than too little. </p> <p> It'd be even better to log <em>only</em> what you need. Not too little, not too much, but just the right amount of logging. Obviously, we should call this <em>Goldilogs</em>. </p> <h3 id="ea53735b49ef4ad7849ebceeabc616ac"> Repeatability <a href="#ea53735b49ef4ad7849ebceeabc616ac" title="permalink">#</a> </h3> <p> How do you know what to log? How do you know that you've logged everything that you'll need, when you don't know your future needs? </p> <p> The key is repeatability. Just like you should be able to <a href="https://en.wikipedia.org/wiki/Reproducible_builds">reproduce builds</a> and <a href="https://en.wikipedia.org/wiki/Continuous_delivery">repeat deployments</a>, you should also be able to reproduce <em>execution</em>. </p> <p> If you can replay what happened when a problem manifested itself, you can troubleshoot it. You need to log just enough data to enable you to repeat execution. How do you identify that data? </p> <p> Consider a line of code like this: </p> <p> <pre><span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">z</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>&nbsp;+&nbsp;<span style="font-weight:bold;color:#1f377f;">y</span>;</pre> </p> <p> Would you log that? </p> <p> It might make sense to log what <code>x</code> and <code>y</code> are, particularly if these values are run-time values (e.g. entered by a user, the result of a web service call, etc.): </p> <p> <pre>Log.<span style="font-weight:bold;color:#74531f;">Debug</span>(<span style="color:#a31515;">$&quot;Adding </span>{<span style="font-weight:bold;color:#1f377f;">x</span>}<span style="color:#a31515;"> and </span>{<span style="font-weight:bold;color:#1f377f;">y</span>}<span style="color:#a31515;">.&quot;</span>); <span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">z</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>&nbsp;+&nbsp;<span style="font-weight:bold;color:#1f377f;">y</span>;</pre> </p> <p> Would you ever log the result, though? </p> <p> <pre>Log.<span style="font-weight:bold;color:#74531f;">Debug</span>(<span style="color:#a31515;">$&quot;Adding </span>{<span style="font-weight:bold;color:#1f377f;">x</span>}<span style="color:#a31515;"> and </span>{<span style="font-weight:bold;color:#1f377f;">y</span>}<span style="color:#a31515;">.&quot;</span>); <span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">z</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>&nbsp;+&nbsp;<span style="font-weight:bold;color:#1f377f;">y</span>; Log.<span style="font-weight:bold;color:#74531f;">Debug</span>(<span style="color:#a31515;">$&quot;Result of addition: </span>{<span style="font-weight:bold;color:#1f377f;">z</span>}<span style="color:#a31515;">&quot;</span>);</pre> </p> <p> There's no reason to log the result of the calculation. Addition is a <a href="https://en.wikipedia.org/wiki/Pure_function">pure function</a>; it's <em>deterministic</em>. If you know the inputs, you can always repeat the calculation to get the output. Two plus two is always four. </p> <p> The more your code is composed from pure functions, the less you need to log. </p> <h3 id="a59305ce898b48879d5ca90db24f243a"> Log only impure actions <a href="#a59305ce898b48879d5ca90db24f243a" title="permalink">#</a> </h3> <p> In principle, all code bases interleave pure functions with impure actions. In most procedural or object-oriented code, no attempt is made of separating the two: </p> <p> <img src="/content/binary/impure-with-stripes-of-purity.png" alt="A box of mostly impure (red) code with vertical stripes of green symbolising pure code."> </p> <p> I've here illustrated impure actions with red and pure functions with green. Imagine that this is a conceptual block of code, with execution flowing from top to bottom. When you write normal procedural or object-oriented code, most of the code will have some sort of local side effect in the form of a state change, a more system-wide side effect, or be non-deterministic. Occasionally, arithmetic calculation or similar will form small pure islands. </p> <p> While you don't need to log the output of those pure functions, it hardly makes a difference, since most of the code is impure. It would be a busy log, in any case. </p> <p> Once you shift towards functional-first programming, your code may begin to look like this instead: </p> <p> <img src="/content/binary/functional-first-impure-pure-box.png" alt="A box of mostly pure (green) code with a few vertical stripes of red symbolising impure code."> </p> <p> You may still have some code that occasionally executes impure actions, but largely, most of the code is pure. If you know the inputs to all the pure code, you can reproduce that part of the code. This means that you only need to log the non-deterministic parts: the impure actions. Particularly, you need to log the outputs from the impure actions, because these impure output values become the inputs to the next pure block of code. </p> <p> This style of architecture is what you'll often get with a well-designed <a href="https://fsharp.org">F#</a> code base, but you can also replicate it in C# or another object-oriented programming language. I'd also draw a diagram like this to illustrate how <a href="https://www.haskell.org">Haskell</a> code works if you <a href="/2017/07/10/pure-interactions">model interactions with free monads</a>. </p> <p> This is the most generally applicable example, so articles in this short series show a Haskell code base with free monads, as well as a C# code base. </p> <p> In reality, you can often get away with an <a href="/2020/03/02/impureim-sandwich">impureim sandwich</a>: </p> <p> <img src="/content/binary/impure-pure-impure-sandwich-box.png" alt="A box with a thin red slice on top, a thick green middle, and a thin red slice at the bottom."> </p> <p> This architecture makes things simpler, including logging. You only need to log the inital and the concluding impure actions. The rest, you can always recompute. </p> <p> I <em>could</em> have implemented the comprehensive example code shown in the next articles as impureim sandwiches, but I chose to use free monads in the Haskell example, and Dependency Injection in the C# example. I did this in order to offer examples from which you can extrapolate a more complex architecture for your production code. </p> <h3 id="28bbf72ea37d47229312d9cf7bf14b9d"> Examples <a href="#28bbf72ea37d47229312d9cf7bf14b9d" title="permalink">#</a> </h3> <p> I've produced two equivalent example code bases to show how to log just enough data. The first is in Haskell because <a href="/2020/02/24/discerning-and-maintaining-purity">it's the best way to be sure that pure and impure code is properly separated</a>. </p> <p> Both example applications have the same externally visible behaviour. They showcase a focused vertical slice of a restaurant reservation system. The only feature they support is the creation of a reservation. </p> <p> Clients make reservations by making an HTTP POST request to the reservation system: </p> <p> <pre>POST /reservations HTTP/1.1 Content-Type: application/json { &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;id&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;84cef648-1e5f-467a-9d13-1b81db7f6df3&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;date&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2021-12-21&nbsp;19:00:00&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;email&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;mark@example.com&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;name&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;Mark&nbsp;Seemann&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;quantity&quot;</span>:&nbsp;4 }</pre> </p> <p> This is an attempt to make a reservation for four people at December 21, 2021 at seven in the evening. Both code bases support this HTTP API. </p> <p> If the web service accepts the reservation, it'll write the reservation as a record in a SQL Server database. The table is defined as: </p> <p> <pre><span style="color:blue;">CREATE</span>&nbsp;<span style="color:blue;">TABLE</span>&nbsp;[dbo]<span style="color:gray;">.</span>[Reservations]<span style="color:blue;">&nbsp;</span><span style="color:gray;">(</span> &nbsp;&nbsp;&nbsp;&nbsp;[Id]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">INT</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:gray;">NOT</span>&nbsp;<span style="color:gray;">NULL</span>&nbsp;<span style="color:blue;">IDENTITY</span><span style="color:gray;">,</span> &nbsp;&nbsp;&nbsp;&nbsp;[Guid]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">UNIQUEIDENTIFIER</span>&nbsp;&nbsp;&nbsp;<span style="color:gray;">NOT</span>&nbsp;<span style="color:gray;">NULL</span>&nbsp;<span style="color:blue;">UNIQUE</span><span style="color:gray;">,</span> &nbsp;&nbsp;&nbsp;&nbsp;[Date]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">DATETIME2</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:gray;">NOT</span>&nbsp;<span style="color:gray;">NULL,</span> &nbsp;&nbsp;&nbsp;&nbsp;[Name]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">NVARCHAR&nbsp;</span><span style="color:gray;">(</span>50<span style="color:gray;">)</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:gray;">NOT</span>&nbsp;<span style="color:gray;">NULL,</span> &nbsp;&nbsp;&nbsp;&nbsp;[Email]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">NVARCHAR&nbsp;</span><span style="color:gray;">(</span>50<span style="color:gray;">)</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:gray;">NOT</span>&nbsp;<span style="color:gray;">NULL,</span> &nbsp;&nbsp;&nbsp;&nbsp;[Quantity]&nbsp;&nbsp;&nbsp;<span style="color:blue;">INT</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:gray;">NOT</span>&nbsp;<span style="color:gray;">NULL</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">PRIMARY</span>&nbsp;<span style="color:blue;">KEY</span>&nbsp;<span style="color:blue;">CLUSTERED&nbsp;</span><span style="color:gray;">(</span>[Id]&nbsp;<span style="color:blue;">ASC</span><span style="color:gray;">)</span></pre> </p> <p> Both implementations of the service can run on the same database. </p> <p> The examples follow in separate articles: <ul> <li><a href="/2020/03/30/repeatable-execution-in-haskell">Repeatable execution in Haskell</a></li> <li><a href="/2020/04/06/repeatable-execution-in-c">Repeatable execution in C#</a></li> </ul> Readers not comfortable with Haskell are welcome to skip directly to the C# article. </p> <h3 id="3068df1aa90b48bab281478d4bbf659c"> Log metadata <a href="#3068df1aa90b48bab281478d4bbf659c" title="permalink">#</a> </h3> <p> In this article series, I focus on run-time data. The point is that there's a formal method to identify what to log: <em>Log the inputs to and outputs from impure actions.</em> </p> <p> I don't focus on metadata, but apart from run-time data, each log entry should be accompanied by metadata. As a minimum, each entry should come with information about the time it was observed, but here's a list of metadata to consider: <ul> <li>Date and time of the log entry. Make sure to include the time zone, or alternatively, log exclusively in UTC.</li> <li>The version of the software that produced the entry. This is particularly important if you deploy new versions of the software several times a day.</li> <li>The user account or security context in which the application runs.</li> <li>The machine ID, if you consolidate server farm logs in one place.</li> <li>Correlation IDs, if present.</li> </ul> I don't claim that this list is complete, but I hope it can inspire you to add the metadata that you need. </p> <h3 id="f8469ec9c7e54089b05c6a84562c404d"> Conclusion <a href="#f8469ec9c7e54089b05c6a84562c404d" title="permalink">#</a> </h3> <p> You only need to log what happens in impure actions. In a normal imperative or object-oriented code base, this is almost a useless selection criterion, because most of what happens is impure. Thus, you need to log almost everything. </p> <p> There's many benefits to be had from moving towards a <a href="/2018/11/19/functional-architecture-a-definition">functional architecture</a>. One of them is that it simplifies logging. Even a functional-first approach, as is often seen in <a href="/2015/08/03/idiomatic-or-idiosyncratic">idiomatic</a> F# code bases, can simplify your logging efforts. The good news is that you can adopt a similar architecture in object-oriented code. You don't even have to compromise the design. </p> <p> I've worked on big C# code bases where we logged all the impure actions. It was typically less than a dozen impure actions per HTTP request. When there was a problem in production, I could usually reproduce what caused it based on the logs. </p> <p> You don't have to <em>overlog</em> to be able to troubleshoot your production code. Log the data that matters, and only that. Log the impure inputs and outputs. </p> <p> <strong>Next:</strong> <a href="/2020/03/30/repeatable-execution-in-haskell">Repeatable execution in Haskell</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header">Comments</h2> <div class="comment" id="a7018cf7caa54fc8962e7dbdea833f94"> <div class="comment-author"><a href="https://www.relativisticramblings.com/">Christer van der Meeren</a></div> <div class="comment-content"> <p> I like the simplicity of "<em>log the impure inputs and outputs</em>", and logging to ensure repeatability. But consider a common workflow: Load a (DDD) aggregate from DB, call pure domain logic it, and store the result. </p> <p> The aggregate may be very complex, e.g. an order with not just many properties itself, but also many sub-entities (line items, etc.) and value objects. In order to get repeatability, you need to log the entire aggregate that was loaded. This is hard/verbose (don't get too tempted by F#'s nice stringification of records and unions – you'll want to avoid logging sensitive information), and you'll still end up with huge multi-line dumps in your log (say, 10 lines for the order and 10 lines per line item = 100 lines for an order with 9 line items, for a single operation / log statement). </p> <p> Intuitively to me, that seems like a silly amount of logging, but I can't see any alternative if you want to get full repeatability in order to debug problems. Thoughts? </p> </div> <div class="comment-date">2020-04-02 10:21 UTC</div> </div> <div class="comment" id="74a774a447f246d0a00d7d2640b9fa96"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> ...you'll want to avoid logging sensitive information... </blockquote> <p> If your application caches sensitive information, then it would be reasonble to only cache an encrypted version. That way, logging the information is not a security issue and neither is holding that infomration in memory (where malware could read it via <a href="https://en.wikipedia.org/wiki/Memory-scraping_malware">memory-scraping</a>). </p> <blockquote> ...you'll still end up with huge multi-line dumps in your log... </blockquote> <p> Not all logging is meant to be directly consumed by humans. <a href="https://github.com/serilog/serilog/wiki/Structured-Data">Structued logging</a> is makes it easy for computers to consume logging events. For an event sourcing architecture (such as the Elm architecture), one can record all events and then create tooling to allow playback. I hope Elmish.WPF gets something like this <a href="https://github.com/elmish/elmish/issues/194#issuecomment-549322498">if/when some of the Fable debugging tools are ported to F#</a>. </p> </div> <div class="comment-date">2020-04-04 19:49 UTC</div> </div> <div class="comment" id="2d78fcdcc4474b3fada0e0a089679c0c"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Christer, thank you for writing. There's two different concerns, as far as I can see. I'd like to start with the size issue. </p> <p> The size of software data is unintuitive to the human brain. A data structure that looks overwhelmingly vast to us is nothing but a few hundred kilobytes in raw data. I often have that discussion regarding API design, but the same arguments could apply to logging. How much would 100 lines of structured JSON entail? </p> <p> Let's assume some that JSON properties are numbers (prices, quantities, IDs, etcetera.) while others could be unbounded strings. Let's assume that the numbers all take up four bytes, while Unicode strings are each 100 bytes on average. The average byte size of a 'line' could be around 50 bytes, depending on the proportion of numbers to strings. 100 lines, then, would be 5,000 bytes, or around 5 kB. </p> <p> Even if data structures were a few orders of magnitude larger, that in itself wouldn't keep me up at night. </p> <p> Of course, that's not the whole story. The <em>volume</em> of data is also important. If you log hundred such entries every second, it obviously adds up. It could be prohibitive. </p> <p> That scenario doesn't fit my experience, but for the sake of argument, let's assume that that's the case. What's the alternative to logging the impure operations? </p> <p> You can decide to log less, but that has to be an explicit architectural decision, because if you do that, there's going to be behaviour that you can't reproduce. Logging all impure operations is the minimum amount of logging that'll guarantee that you can fully reproduce all behaviour. You may decide that there's behaviour that you don't need to be able to reconstruct, but I think that this ought to be an explicit decision. </p> <p> There may be a better alternative. It also addresses the issue regarding sensitive data. </p> <p> Write pure functions that take as little input as possible, and produce as little output as possible. In the realm of security design there's the concept of <a href="https://martinfowler.com/bliki/Datensparsamkeit.html">datensparsamkeit</a> (data frugality). Only deal with the data you really need. </p> <p> Does that pure function really need to take as input an entire aggregate, or would a smaller projection do? If the latter, implement the impure operation so that it returns the projection. That's a smaller data set, so less to log. </p> <p> The same goes for sensitive input. Perhaps instead of a <a href="/2018/12/10/danish-cpr-numbers-in-f">CPR number</a> the function only needs an age value. If so, then you only need to log the age. </p> <p> These are deliberate design decision you must take. You don't get such solutions for free, but you can if you will. </p> </div> <div class="comment-date">2020-04-09 15:06 UTC</div> </div> <div class="comment" id="77d77a57bef8407bb7dfd08f6305236b"> <div class="comment-author"><a href="https://www.relativisticramblings.com/">Christer van der Meeren</a></div> <div class="comment-content"> <p> Thank you for the reply. It makes sense that this should be a deliberate design decision. </p> <p> I'm working full-time with F# myself, and would be very interested in seeing how you think this could be solved in F#. In this series, you are demonstrating solutions for Haskell (free monads) and C# (dependency injection), but as you have alluded to previously on your blog, neither of those are idiomatic solutions in F# (free monads are cumbersome without higher-kinded types, and DI primarily fits an object-oriented architecture). </p> <p> I realize you may not choose to write another blog post in this series tackling F# (though it would nicely "fill the gap" between Haskell and C#, and you're definitely the one to write it!), but even a few keywords/pointers would be helpful. </p> </div> <div class="comment-date">2020-04-10 20:54 UTC</div> </div> <div class="comment" id="ed430ce7df87483dbce0f91d498b561e"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Christer, thank you for writing. I am, indeed, not planning to add another article to this small series. Not that writing the article itself would be too much trouble, but in order to stay on par with the two other articles, I'd have to develop the corresponding F# code base. That currently doesn't look like it'd be the best use of my time. </p> <p> In F# you can <a href="/2017/01/30/partial-application-is-dependency-injection">use partial application for dependency injection</a>. I hope that nothing I wrote gave the impression that this isn't <a href="/2015/08/03/idiomatic-or-idiosyncratic">idiomatic</a> F#. What I've demonstrated is that it isn't <a href="/2018/11/19/functional-architecture-a-definition">functional</a>, but since F# is a multiparadigmatic language, that's still fine. </p> <p> The <a href="/2020/04/06/repeatable-execution-in-c">C# example in this article series</a> shows what's essentially an <a href="/2020/03/02/impureim-sandwich">impureim sandwich</a>, so it shouldn't be too hard to translate that architecture to F#. It's already quite functional. </p> </div> <div class="comment-date">2020-04-14 8:03 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Conway's Law: latency versus throughput https://blog.ploeh.dk/2020/03/16/conways-law-latency-versus-throughput 2020-03-16T06:46:00+00:00 Mark Seemann <div id="post"> <p> <em>Organising work in one way optimises for low latency; in another for throughput.</em> </p> <p> It's a cliché that the software industry is desperate for talent. I also believe that it's a myth. As I've <a href="/2015/12/04/the-rules-of-attraction-location">previously observed</a>, the industry seems desperate for talent <em>within commute range</em>. The implication is that although we perform some of the most intangible and digitised work imaginable, we're expected to be physically present in an office. </p> <p> Since 2014 I've increasingly been working from home, and I love it. I also believe that it's an efficient way to develop software, but not only for the reasons usually given. </p> <p> I believe that distributed, asynchronous software development optimises throughput, but may sacrifice reaction time (i.e. increase latency). </p> <h3 id="dda9b0cd03e941c79365f6ff81969107"> The advantages of working in an office <a href="#dda9b0cd03e941c79365f6ff81969107" title="permalink">#</a> </h3> <p> It's easy to criticise office work, but if it's so unpopular, why is it still the mainstream? </p> <p> I think that there's a multitude of answers to that question. One is that this may be the only way that management can imagine. Since programming is so intangible, it's impossible to measure productivity. What a manager <em>can</em> do, though, is to watch who arrives early, who's the last to leave, and who seems to be always in front of his or her computer, or in a meeting, and so on. </p> <p> Another answer to the question is that people actually <em>like</em> working together. I currently advice <a href="https://idq.dk">IDQ</a> on software development principles and architecture. They have a tight-knit development team. The first day I visited them, I could feel a warm and friendly vibe. I've been visiting them regularly for about a year, now, and the first impression has proven correct. As we Danes say, that work place is positively <a href="https://en.wikipedia.org/wiki/Hygge">hyggelig</a>. </p> <p> Some people also prefer to go to the office to have a formal boundary between their professional and private lives. </p> <p> Finally, if you're into agile software development, you've probably heard about the benefits of <em>team co-location</em>. </p> <p> When the team is located in the same room, working towards the same goals, communication is <em>efficient</em> - or is it? </p> <p> You can certainly get answers to your questions quickly. All you have to do is to <em>interrupt</em> the person who can answer. If you don't know who that is, you just interrupt everybody until you've figured it out. While offices are interruption factories (as <a href="https://dhh.dk">DHH</a> puts it), this style of work can reduce latency. </p> <p> If you explicitly follow e.g. <a href="http://amzn.to/108Pxzb">lean software development</a> and implement something like <em>one-piece flow</em>, you can reduce your cycle time. The less delay between activities, the faster you can deliver value. Once you've delivered one piece (e.g. a <em>feature</em>), you move on to the next. </p> <p> <img src="/content/binary/one-piece-flow.png" alt="Alternating blocks of activities and delays going from left to right."> </p> <p> If this is truly the goal, then putting all team members in the same office makes sense. You don't get higher communications bandwidth than when you're physically together. All the subtle intonations of the way your colleagues speak, the non-verbal cues, etcetera are there if you know how to interpret them. </p> <h3 id="da39de4510544526b6234fa7d75e50bc"> Consequences of team co-location <a href="#da39de4510544526b6234fa7d75e50bc" title="permalink">#</a> </h3> <p> I've seen team co-location work for small teams. People can <a href="https://en.wikipedia.org/wiki/Pair_programming">pair program</a> or even <a href="https://en.wikipedia.org/wiki/Mob_programming">mob program</a>. You can easily draw on the expertise of your co-workers. It does require, however, that everyone respects boundaries. </p> <p> It's a balancing act. You may get your answer sooner, but your interruption could break your colleague's concentration. The net result could be negative productivity. </p> <p> While I've seen team co-location work, I've seen it fail more frequently. There are many reasons for this. </p> <p> First, there's all the interruptions. Most programmers don't like being interrupted. </p> <p> Second, the opportunity for ad-hoc communication easily leads to poor software architecture. This follows from <a href="https://en.wikipedia.org/wiki/Conway%27s_law">Conway's law</a>, which argues that <blockquote> <p> "Any organization that designs a system [...] will inevitably produce a design whose structure is a copy of the organization's communication structure." </p> <footer><cite><a href="http://www.melconway.com/Home/Committees_Paper.html">Melvin Conway</a></cite></footer> </blockquote> </p> <p> I know that it's not a law in any rigid sense of the word, but it can often be fruitful to keep an eye out for this sort of interaction. Based on my experience, it seems to happen often. </p> <p> Ad-hoc office communication leads to ad-hoc communication structures in the code. There's typically little explicit architecture. Knowledge is in the heads of people. </p> <p> Such an organisation tends to have an oral culture. There's no permanence of knowledge, no emphasis on readability of code (because you can always ask someone if there's code you don't understand), and meetings all the time. </p> <p> I once worked as a consultant for a company where there was only one old-timer around. He spent most of his time in meetings, because he knew all the intricate details of how everything worked and talked together, and other people needed to know. </p> <p> After I'd been involved with that (otherwise wonderful) company on and off for a few years, I accumulated some knowledge as well, and people wanted to have meetings with me. </p> <p> In the beginning, I obliged. Then it turned out that a week after I'd had a meeting, I'd be called to what would essentially be <em>the same</em> meeting again. Why? Because some other stakeholder heard about the first meeting and decided that he or she also required that information. The solution? Call another meeting. </p> <p> My counter-move was to begin to write things down. When people would call a meeting, I'd ask for an agenda. That alone filtered away more than half of the meetings. When I did receive an agenda, I could often reply: </p> <p> "Based on the agenda, I believe you'll find everything you need to know <em>here</em>. If not, please let me know what's missing so that I can update the document" </p> <p> I'd attach said document. By doing that, I eliminated ninety percent of my meetings. </p> <p> Notice what I did. I changed the communication structure - at least locally around me. Soon after, I went remote with that client, and had a few successful years doing that. </p> <p> I hope that the previous section outlined that working in an office can be effective, but as I've now outlined, it can also be dysfunctional. </p> <p> If you truly must deliver as soon as possible, because if you don't, the organisation isn't going to be around in five years, office work, with its low communications latency may be the best option. </p> <h3 id="e9958e6f5b75431987f76b9d084b1e30"> Remote office work <a href="#e9958e6f5b75431987f76b9d084b1e30" title="permalink">#</a> </h3> <p> I often see companies advertise for programmers. When remote work is an option, it often comes with the qualification that it must be within a particular country, or a particular time zone. </p> <p> There can be legal or bureaucratic reasons why a company only wants to hire within a country. I get that, but I consider a time zone requirement a danger sign. The same goes for <em>"we use Slack"</em> or whatever other 'team room' instant messaging technology is cool these days. </p> <p> That tells me that while the company allows people to be physically not in the office, they must still obey office hours. This indicates to me that communication remains ad-hoc and transient. Again, <a href="/2019/03/04/code-quality-is-not-software-quality">code quality</a> suffers. </p> <p> These days, because of the Corona virus, many organisations deeply entrenched in the oral culture of co-location find that they must now work as a distributed team. They try to address the situation by setting up day-long video conference calls. </p> <p> It may work in an office, but it's not the best fit for a distributed team. </p> <h3 id="1dd79d5d27e44a4da134a08a0df29fc4"> Distributed asynchronous software development <a href="#1dd79d5d27e44a4da134a08a0df29fc4" title="permalink">#</a> </h3> <p> Decades of open-source development has shown another way. Successful open-source software (OSS) projects are distributed and use asynchronous communication channels (mailing lists, issue trackers). It's worth considering the causation. I don't think anyone sat down and decided to do it this way in order to be successful. I think that the OSS projects that became successful became successful exactly because they organised work that way. </p> <p> When contributions are voluntary, you have to cast a wide net. A successful OSS project should accept contributions from around the world. If an excellent contribution from Japan falters because the project team is based in the US, and immediate, real-time communication is required, then that project has odds against it. </p> <p> An OSS project that works asynchronously can receive contributions from any time zone. The disadvantage can be significant communication lag. </p> <p> If you get a contribution from Australia, but you're in Europe, you may send a reply asking for clarifications or improvements. At the time you do that, the contributor may have already gone to bed. He or she isn't going to reply later, at which time you've gone to bed. </p> <p> It can take days to get anything done. That doesn't sound efficient, and if you're in a <em>one-piece flow</em> mindset it isn't. You need to enable parallel development. If you do that, you can work on something else while you wait for your asynchronous collaborator to respond. </p> <p> <img src="/content/binary/one-piece-flow-vs-paralle-development.png" alt="A diagram juxtaposing two pieces finished one after the other, against two pieces finished in parallel."> </p> <p> In this diagram, the wait-times in the production of one piece (e.g. one feature) can be used to move forward with another feature. The result is that you may actually be able to finish both tasks sooner than if you stick strictly to one-piece flow. </p> <p> Before you protest: in reality, delay times are much longer than implied by the diagram. An activity could be something as brief as responding to a request for more information. You may be able to finish this activity in 30 minutes, whereafter the delay time is another twenty hours. Thus, in order to keep throughput comparable, you need to juggle not two, but dozens of parallel processes. </p> <p> You may also feel the urge to protest that the diagram postulates a false dichotomy. That's not my intention. Even with co-location, you could do parallel development. </p> <p> There's also the argument that parallel development requires context switching. That's true, and it comes with overhead. </p> <p> My argument is only this: if you decide to shift to an asynchronous process, then I consider parallel development essential. Even with parallel development, you can't get the same (low) latency as is possible in the office, but you may be able to get better throughput. </p> <p> This again has implications for software architecture. Parallel development works when features can be developed independently of each other - when there's only minimal dependencies between various areas of the code. </p> <p> Conway's law is relevant here as well. If you decouple the communication between various parts of the system, you can also decouple the development of said parts. Ultimately, the best fit for a distributed, asynchronous software development <em>process</em> may be a distributed, asynchronous system. </p> <h3 id="f02f525b49564f1fadfa27d471f41e06"> Quadrants <a href="#f02f525b49564f1fadfa27d471f41e06" title="permalink">#</a> </h3> <p> This is the point where, if this was a Gartner report, it'd include a 2x2 table with four quadrants. It's not, but I'll supply it anyway: <table> <thead> <tr> <td></td> <td>Synchronous</td> <td>Asynchronous</td> </tr> </thead> <tbody> <tr> <td>Distributed</td> <td>Virtual office</td> <td>OSS-like parallel development</td> </tr> <tr> <td>Co-located</td> <td>Scrum, XP, etc.</td> <td>Emailing the person next to you</td> </tr> </tbody> </table> The current situation where the oral, co-located teams find themselves forced to work remotely is what I call the <em>virtual office</em>. If the Corona outbreak is over in weeks, it's probably best to just carry on in that way. I don't, however, think it's a sustainable process model. There's still too much friction involved in having to be connected to a video conference call for 8 hours each day. Long-term, I think that a migration towards a distributed, asynchronous process would be beneficial. </p> <p> I've yet to discuss the fourth quadrant. This is where people sit next to each other, yet still email each other. That's just weird. Like the <em>virtual office</em>, I don't think it's a long-term sustainable process. The advantages of just talking to each other is just too great. If you're co-located, ad-hoc communication is possible, so that's where the software architecture will gravitate as well. Again, Conway's law applies. </p> <p> If you want to move towards a sustainable distributed process, you should consider adjusting everything accordingly. A major endeavour in that shift involves migrating from an oral to a written culture. <a href="https://basecamp.com/guides/how-we-communicate">Basecamp has a good guide to get you started.</a> </p> <h3 id="d0381a7649cb40deab87c4388001f339"> Your writer reveals himself <a href="#d0381a7649cb40deab87c4388001f339" title="permalink">#</a> </h3> <p> I intend this to be an opinion piece. It's based on a combination of observations made by others, mixed with my personal experiences, but I also admit that it's coloured by my personal preferences. I strongly prefer distributed, asynchronous processes with an emphasis on written communication. Since this blog contains more than 500 articles, it should hardly come as a surprise to anyone that I'm a prolific writer. </p> <p> I've had great experiences with distributed, asynchronous software development. One such experience was the decade I led the <a href="https://github.com/AutoFixture/AutoFixture">AutoFixture</a> open-source project. Other experiences include a handful of commercial, closed-source projects where I did the bulk of the work remotely. </p> <p> This style of work benefits my employer. By working asynchronously, I have to document what I do, and why I do it. I leave behind a trail of text artefacts other people can consult when I'm not available. </p> <p> I like asynchronous processes because they liberate me to work when I want to, where I want to. I take advantage of this to go for a run during daylight hours (otherwise an issue during Scandinavian winters), to go grocery shopping outside of rush hour, to be with my son when he comes home from school, etcetera. I compensate by working at other hours (evenings, weekends). This isn't a lifestyle that suits everyone, but it suits me. </p> <p> This preference produces a bias in the way that I see the world. I don't think I can avoid that. Like DHH I view offices as interruption factories. I self-identify as an introvert. I like being alone. </p> <p> Still, I've tried to describe some forces that affect how work is done. I've tried to be fair to co-location, even though I don't like it. </p> <h3 id="b8e64a09f56345c883b596ff612f942f"> Conclusion <a href="#b8e64a09f56345c883b596ff612f942f" title="permalink">#</a> </h3> <p> Software development with a co-located team can be efficient. It offers the benefits of high-bandwidth communication, pair programming, and low-latency decision making. It also implies an oral tradition. Knowledge has little permanence and the team is vulnerable to key team members going missing. </p> <p> While such a team organisation can work well when team members are physically close to each other, I believe that this model comes under pressure when team members work remotely. I haven't seen the oral, ad-hoc team process work well in a distributed setting. </p> <p> Successful distributed software development is asynchronous and based on a literate culture. It only works if the software architecture allows it. Code has to be decoupled and independently deployable. If it is, though, you can perform work in parallel. Conway's law still applies. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Polymorphic Builder https://blog.ploeh.dk/2020/03/09/polymorphic-builder 2020-03-09T06:47:00+00:00 Mark Seemann <div id="post"> <p> <em>Keeping illegal states unrepresentable with the Builder pattern.</em> </p> <p> As a reaction to <a href="/2020/02/10/builder-isomorphisms">my article on Builder isomorphisms</a> Tyson Williams asked: <blockquote> <p> "If a <code>GET</code> or <code>DELETE</code> request had a body or if a <code>POST</code> request did not have a body, then I would suspect that such behavior was a bug. </p> <p> "For the sake of a question that I would like to ask, let's suppose that a body must be added if and only if the method is <code>POST</code>. Under this assumption, <code>HttpRequestMessageBuilder</code> can create invalid messages. For example, it can create a <code>GET</code> request with a body, and it can create a <code>POST</code> request without a body. Under this assumption, how would you modify your design so that only valid messages can be created?" </p> </blockquote> I'm happy to receive that question, because I struggled to find a compelling example of a <a href="https://en.wikipedia.org/wiki/Builder_pattern">Builder</a> where polymorphism seems warranted. Here, it does. </p> <h3 id="49a6ffa95ffd44dfbf7c1160879af8e9"> Valid combinations <a href="#49a6ffa95ffd44dfbf7c1160879af8e9" title="permalink">#</a> </h3> <p> Before showing code, I think a few comments are in order. As far as I'm aware, the HTTP specification doesn't prohibit weird combinations like a <code>GET</code> request with a body. Still, such a combination is so odd that it seems fair to design an API to prevent this. </p> <p> On the other hand I think that a <code>POST</code> request without a body should still be allowed. It's not too common, but there are edge cases where this combination is valid. If you want to cause a side effect to happen, a <code>GET</code> is inappropriate, but sometimes all you want do to is to produce an effect. In the <a href="http://amzn.to/YFnkRg">Restful Web Services Cookbook</a> Subbu Allamaraju gives this example of a <em>fire-and-forget bulk task:</em> </p> <p> <pre>POST /address-correction?before=2010-01-01 HTTP/1.1</pre> </p> <p> As he puts it, <em>"in essence, the client is "flipping a switch" to start the work."</em> </p> <p> I'll design the following API to allow this combination, also because it showcases how that sort of flexibility can still be included. On the other hand, I'll prohibit the combination of a request body in a <code>GET</code> request, as Tyson Williams suggested. </p> <h3 id="5509ba650064423097e277f6f532d578"> Expanded API <a href="#5509ba650064423097e277f6f532d578" title="permalink">#</a> </h3> <p> I'll expand on the <code>HttpRequestMessageBuilder</code> example shown in the previous article. As <a href="/2020/02/17/builder-as-a-monoid#6d834828809b4ac2b36f59bb244e5952">outlined in another article</a>, apart from the <code>Build</code> method the Builder really only has two capabilities: <ul> <li>Change the HTTP method</li> <li>Add (or update) a JSON body</li> </ul> These are the two combinations we now need to model differently. If I do that now, there'd be no other affordances offered by the Builder API. In order to make the example more explicit, I'll first add a pair of new capabilities: <ul> <li>Add or change the <code>Accept</code> header</li> <li>Add or change a <code>Bearer</code> token</li> </ul> When I do that, the <code>HttpRequestMessageBuilder</code> class now looks like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;url; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">object</span>?&nbsp;jsonBody; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">string</span>?&nbsp;acceptHeader; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">string</span>?&nbsp;bearerToken; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Uri</span>(<span style="font-weight:bold;color:#1f377f;">url</span>))&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;: &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>(<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:#2b91af;">HttpMethod</span>.Get,&nbsp;<span style="color:blue;">null</span>,&nbsp;<span style="color:blue;">null</span>,&nbsp;<span style="color:blue;">null</span>)&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">method</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">object</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">acceptHeader</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">bearerToken</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.url&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Method&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">method</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.jsonBody&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.acceptHeader&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">acceptHeader</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.bearerToken&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">bearerToken</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;Method&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;url, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;jsonBody, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acceptHeader, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;url, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Method, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acceptHeader, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithAcceptHeader</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newAcceptHeader</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;url, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Method, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;jsonBody, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">newAcceptHeader</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithBearerToken</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newBearerToken</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;url, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Method, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;jsonBody, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acceptHeader, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">newBearerToken</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Build</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>(Method,&nbsp;url); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">BuildBody</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">AddAcceptHeader</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">AddBearerToken</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BuildBody</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(jsonBody&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">json</span>&nbsp;=&nbsp;<span style="color:#2b91af;">JsonConvert</span>.<span style="color:#74531f;">SerializeObject</span>(jsonBody); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Content&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">StringContent</span>(<span style="font-weight:bold;color:#1f377f;">json</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Content.Headers.ContentType.MediaType&nbsp;=&nbsp;<span style="color:#a31515;">&quot;application/json&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddAcceptHeader</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(acceptHeader&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Headers.Accept.<span style="font-weight:bold;color:#74531f;">ParseAdd</span>(acceptHeader); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddBearerToken</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(bearerToken&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Headers.Authorization&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AuthenticationHeaderValue</span>(<span style="color:#a31515;">&quot;Bearer&quot;</span>,&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> Notice that I've added the methods <code>WithAcceptHeader</code> and <code>WithBearerToken</code>, with supporting implementation. So far, those are the only changes. </p> <p> It enables you to build HTTP request messages like this: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithBearerToken</span>(<span style="color:#a31515;">&quot;cGxvZWg=&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> Or this: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>.Post) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">new</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;id&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">NewGuid</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2021-02-09&nbsp;19:15:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Hervor&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;email&nbsp;=&nbsp;<span style="color:#a31515;">&quot;hervor@example.com&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;quantity&nbsp;=&nbsp;2 &nbsp;&nbsp;&nbsp;&nbsp;}) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithAcceptHeader</span>(<span style="color:#a31515;">&quot;application/vnd.foo.bar+json&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithBearerToken</span>(<span style="color:#a31515;">&quot;cGxvZWg=&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> It still doesn't address Tyson Williams' requirement, because you can build an HTTP request like this: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">new</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;id&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">NewGuid</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2020-03-22&nbsp;19:30:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Ælfgifu&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;email&nbsp;=&nbsp;<span style="color:#a31515;">&quot;ælfgifu@example.net&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;quantity&nbsp;=&nbsp;1&nbsp;}) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> Recall that the default HTTP method is <code>GET</code>. Since the above code doesn't specify a method, it creates a <code>GET</code> request with a message body. That's what shouldn't be possible. Let's <a href="https://blog.janestreet.com/effective-ml-video">make illegal states unrepresentable</a>. </p> <h3 id="95ac7d907e2b461ea56247bfe4eec6da"> Builder interface <a href="#95ac7d907e2b461ea56247bfe4eec6da" title="permalink">#</a> </h3> <p> Making illegal states unrepresentable is a catch phrase coined by <a href="https://twitter.com/yminsky">Yaron Minsky</a> to describe advantages of statically typed functional programming. Unintentionally, it also describes a fundamental tenet of object-oriented programming. In <a href="http://amzn.to/1claOin">Object-Oriented Software Construction</a> Bertrand Meyer describes object-oriented programming as the discipline of guaranteeing that an object can never be in an invalid state. </p> <p> In the present example, we can't allow an arbitrary HTTP Builder object to afford an operation to add a body, because that Builder object might produce a <code>GET</code> request. On the other hand, there are operations that are <em>always</em> legal: adding an <code>Accept</code> header or a <code>Bearer</code> token. Because these operations are always legal, they constitute a shared API. Extract those to an interface: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithAcceptHeader</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newAcceptHeader</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithBearerToken</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newBearerToken</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Build</span>(); }</pre> </p> <p> Notice that both the <code>With[...]</code> methods return the new interface. Any <code>IHttpRequestMessageBuilder</code> must implement the interface, but is free to support other operations not part of the interface. </p> <h3 id="23af7eedc51441118c8bd8819f9b3ce3"> HTTP GET Builder <a href="#23af7eedc51441118c8bd8819f9b3ce3" title="permalink">#</a> </h3> <p> You can now implement the interface to build HTTP <code>GET</code> requests: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">HttpGetMessageBuilder</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;url; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">string</span>?&nbsp;acceptHeader; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">string</span>?&nbsp;bearerToken; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpGetMessageBuilder</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Uri</span>(<span style="font-weight:bold;color:#1f377f;">url</span>))&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpGetMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:blue;">null</span>,&nbsp;<span style="color:blue;">null</span>)&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">HttpGetMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">acceptHeader</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">bearerToken</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.url&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.acceptHeader&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">acceptHeader</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.bearerToken&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">bearerToken</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithAcceptHeader</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newAcceptHeader</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpGetMessageBuilder</span>(url,&nbsp;<span style="font-weight:bold;color:#1f377f;">newAcceptHeader</span>,&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithBearerToken</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newBearerToken</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpGetMessageBuilder</span>(url,&nbsp;acceptHeader,&nbsp;<span style="font-weight:bold;color:#1f377f;">newBearerToken</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Build</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>(<span style="color:#2b91af;">HttpMethod</span>.Get,&nbsp;url); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">AddAcceptHeader</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">AddBearerToken</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddAcceptHeader</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(acceptHeader&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Headers.Accept.<span style="font-weight:bold;color:#74531f;">ParseAdd</span>(acceptHeader); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddBearerToken</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(bearerToken&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Headers.Authorization&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AuthenticationHeaderValue</span>(<span style="color:#a31515;">&quot;Bearer&quot;</span>,&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> Notice that the <code>Build</code> method hard-codes <code>HttpMethod.Get</code>. When you're using an <code>HttpGetMessageBuilder</code> object, you can't modify the HTTP method. You also can't add a request body, because there's no API that affords that operation. </p> <p> What you <em>can</em> do, for example, is to create an HTTP request with an <code>Accept</code> header: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpGetMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithAcceptHeader</span>(<span style="color:#a31515;">&quot;application/vnd.foo.bar+json&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> This creates a request with an <code>Accept</code> header, but no <code>Bearer</code> token. </p> <h3 id="b96c590c45394c1d86ec0ff841b82a52"> HTTP POST Builder <a href="#b96c590c45394c1d86ec0ff841b82a52" title="permalink">#</a> </h3> <p> As a peer to <code>HttpGetMessageBuilder</code> you can implement the <code>IHttpRequestMessageBuilder</code> interface to support <code>POST</code> requests: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;url; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">object</span>?&nbsp;jsonBody; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">string</span>?&nbsp;acceptHeader; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">string</span>?&nbsp;bearerToken; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Uri</span>(<span style="font-weight:bold;color:#1f377f;">url</span>))&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:blue;">null</span>,&nbsp;<span style="color:blue;">null</span>,&nbsp;<span style="color:blue;">null</span>)&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>)&nbsp;: &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Uri</span>(<span style="font-weight:bold;color:#1f377f;">url</span>),&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) &nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>)&nbsp;: &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>(<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>,&nbsp;<span style="color:blue;">null</span>,&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">object</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">acceptHeader</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">bearerToken</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.url&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.jsonBody&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.acceptHeader&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">acceptHeader</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.bearerToken&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">bearerToken</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithAcceptHeader</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newAcceptHeader</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;url, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;jsonBody, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">newAcceptHeader</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithBearerToken</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newBearerToken</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;url, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;jsonBody, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acceptHeader, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">newBearerToken</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Build</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>(<span style="color:#2b91af;">HttpMethod</span>.Post,&nbsp;url); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">BuildBody</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">AddAcceptHeader</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">AddBearerToken</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BuildBody</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(jsonBody&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">json</span>&nbsp;=&nbsp;<span style="color:#2b91af;">JsonConvert</span>.<span style="color:#74531f;">SerializeObject</span>(jsonBody); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Content&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">StringContent</span>(<span style="font-weight:bold;color:#1f377f;">json</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Content.Headers.ContentType.MediaType&nbsp;=&nbsp;<span style="color:#a31515;">&quot;application/json&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddAcceptHeader</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(acceptHeader&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Headers.Accept.<span style="font-weight:bold;color:#74531f;">ParseAdd</span>(acceptHeader); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddBearerToken</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(bearerToken&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Headers.Authorization&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AuthenticationHeaderValue</span>(<span style="color:#a31515;">&quot;Bearer&quot;</span>,&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> This class affords various constructor overloads. Two of them don't take a JSON body, and two of them do. This supports both the case where you do want to supply a request body, and the edge case where you don't. </p> <p> I didn't add an explicit <code>WithJsonBody</code> method to the class, so you can't change your mind once you've created an instance of <code>HttpPostMessageBuilder</code>. The only reason I didn't, though, was to save some space. You can add such a method if you'd like to. As long as it's not part of the interface, but only part of the concrete <code>HttpPostMessageBuilder</code> class, illegal states are still unrepresentable. You can represent a <code>POST</code> request with or without a body, but you can't represent a <code>GET</code> request with a body. </p> <p> You can now build requests like this: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;id&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">NewGuid</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2021-02-09&nbsp;19:15:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Hervor&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;email&nbsp;=&nbsp;<span style="color:#a31515;">&quot;hervor@example.com&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;quantity&nbsp;=&nbsp;2 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithAcceptHeader</span>(<span style="color:#a31515;">&quot;application/vnd.foo.bar+json&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithBearerToken</span>(<span style="color:#a31515;">&quot;cGxvZWg=&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> This builds a <code>POST</code> request with both a JSON body, an <code>Accept</code> header, and a <code>Bearer</code> token. </p> <h3 id="4104677292a94451a896e6bee22df93a"> Is polymorphism required? <a href="#4104677292a94451a896e6bee22df93a" title="permalink">#</a> </h3> <p> In <a href="/2020/02/10/builder-isomorphisms">my previous Builder article</a>, I struggled to produce a compelling example of a polymorphic Builder. It seems that I've now mended the situation. Or have I? </p> <p> Is the <code>IHttpRequestMessageBuilder</code> interface really required? </p> <p> Perhaps. It depends on your usage scenarios. I can actually delete the interface, and none of the usage examples I've shown here need change. </p> <p> On the other hand, had I written helper methods against the interface, obviously I couldn't just delete it. </p> <p> The bottom line is that polymorphism can be helpful, but it still strikes me as being non-essential to the Builder pattern. </p> <h3 id="07ed5f99efb549509a3af0c7b510553a"> Conclusion <a href="#07ed5f99efb549509a3af0c7b510553a" title="permalink">#</a> </h3> <p> In this article, I've shown how to guarantee that Builders never get into invalid states (according to the rules we've arbitrarily established). I used the common trick of <a href="/2011/05/30/DesignSmellDefaultConstructor">using constructors for object initialisation</a>. If a constructor completes without throwing an exception, we should expect the object to be in a valid state. The price I've paid for this design is some code duplication. </p> <p> You may have noticed that there's duplicated code between <code>HttpGetMessageBuilder</code> and <code>HttpPostMessageBuilder</code>. There are ways to address that concern, but I'll leave that as an exercise. </p> <p> For the sake of brevity, I've only shown examples written as Immutable Fluent Builders. You can refactor all the examples to mutable Fluent Builders or to the original Gang-of-Four Builder pattern. This, too, will remain an exercise for the interested reader. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="c1ea86ea39814f278e1a19f82b45622b"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> I'm happy to receive that question, because I struggled to find a compelling example of a Builder where polymorphism seems warranted. Here, it does. </blockquote> <p> I know of essentially one occurrence in .NET. Starting with <code>IEnumerable&lt;T&gt;</code>, calling either of the extension methods <a href="https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable.orderby?view=netframework-4.8">OrderBy</a> or <a href="https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable.orderbydescending?view=netframework-4.8">OrderByDescending</a> returns <code>IOrderedEnumerable&lt;T&gt;</code>, which has the additional extension methods <a href="https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable.thenby?view=netframework-4.8">ThenBy</a> and <a href="https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable.thenbydescending?view=netframework-4.8">ThenByDescending</a>. </p> <p> Quoting your recent <a href="https://blog.ploeh.dk/2020/02/10/builder-isomorphisms/">Builder isomorphisms</a> post. </p> <blockquote> The Builder pattern isn't useful only because it enables you to "separate the construction of a complex object from its representation." It's useful because it enables you to present an API that comes with good default behaviour, but which can be tweaked into multiple configurations. </blockquote> <p> I also find the builder pattern useful because its methods typically accept one argument one at a time. The builders in your recent posts are like this. The <code>OrderBy</code> and <code>ThenBy</code> methods and their <code>Descending</code> alternatives in .NET are also examples of this. </p> <p> However, some of the builders in your recent posts have some constructors that take multiple arguments. That is the situation that I was trying to address when <a href="https://blog.ploeh.dk/2017/09/11/test-data-without-builders/#b30ddcf557964bf2a7b63c0e247294e1">I asked</a> </p> <blockquote> Have you ever written a builder that accepted multiple arguments one at a time none of which have reasonable defaults? </blockquote> <p> This could be a <a href="https://blog.ploeh.dk/2020/01/13/on-doing-katas/">kata variation</a>: all public functions accept at most one argument. So <code>Foo(a, b)</code> would not be allowed but <code>Foo.WithA(a).WithB(b)</code> would. In an issue on this blog's GitHub, jaco0646 nicely summerized the reasoning that could lead to applying this design philosophy to production code by <a href="https://github.com/ploeh/ploeh.github.com/issues/539#issuecomment-585837934">saying</a> </p> <blockquote> Popular advice for a builder with required parameters is to put those in a constructor; but with more than a handful of required parameters, we return to the original problem: too much complexity in a constructor. </blockquote> <p> That comment by jaco0646 also supplied names by which this type of design is known. Those names (with the same links from the comment) are <a href="https://blog.jayway.com/2012/02/07/builder-pattern-with-a-twist/">Builder with a twist</a> or <a href="https://rdafbn.blogspot.com/2012/07/step-builder-pattern_28.html">Step Builder</a>. This is great, because I didn't have any good names. (I vaguely recall once thinking that another name was "progressive API" or "progressive fluent API", but now when I search for anything with "progressive", all I get are false positives for <a href="https://en.wikipedia.org/wiki/Progressive_web_application">progressive web app</a>. </p> <p> When replacing a multi-argument constructor with a sequence of function calls that each accept one argument, care must be taken to ensure that illegal state remains unrepresentable. My general impression is that many libraries have designed such APIs well. The two that I have enough experience with to recommend as good examples of this design are the <a href="https://www.learnentityframeworkcore.com/configuration/fluent-api">fluent configuration API in Entity Framework</a> and <a href="https://fluentassertions.com/introduction">Fluent Assertions</a>. As I <a href="https://blog.ploeh.dk/2017/09/11/test-data-without-builders/#be62acdf925841e09485f4253ab0c5fe">said before</a>, the most formal treatment I have seen about this type of API design was in <a href="https://blog.jooq.org/2012/01/05/the-java-fluent-api-designer-crash-course/">this blog post</a>. </p> </div> <div class="comment-date">2020-03-11 17:57 UTC</div> </div> <div class="comment" id="d31b6312b4204c7e8a1c047ed49cd4e6"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, apart from as <a href="/2020/01/13/on-doing-katas">a kata constraint</a>, is there any reason to prefer such a design? </p> <p> I'll be happy to give it a more formal treatment if there's reasonable scenario. Can you think of one? </p> <p> I don't find the motivation given by jaco0646 convincing. If you have more than a handful of required parameters, I agree that that's an issue with complexity, but I don't agree that the solution is to add more complexity on top of it. Builders add complexity. </p> <p> At a glance, though, with something like <code>Foo.WithA(a).WithB(b)</code> it seems to me that you're essentially reinventing <a href="https://en.wikipedia.org/wiki/Currying">currying</a> the hard way around. </p> <p> Related to the overall Builder discussion (but not to currying) you may also find <a href="https://blog.frankel.ch/builder-pattern-finite-state-machine">this article</a> and <a href="https://stackoverflow.com/a/2267467/126014">this Stack Overflow answer</a> interesting. </p> </div> <div class="comment-date">2020-03-13 6:19 UTC</div> </div> <div class="comment" id="b30263d2a8e440e7b89dc23bd9d8d3c6"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> ...is there any reason to prefer such a design? </blockquote> <p> Yes. Just like you, I want to write <a href="https://blog.ploeh.dk/2019/11/04/the-80-24-rule/">small functions</a>. In that post, you suggest an arbitrary maximum of 24 lines. One thing I find fascinating about functional programming is how useful the common functions are (such as <code>map</code>) and how they are implemented in only a few lines (often just one line). There is a correlation between the number of function arguments and the length of the function. So to help control the length of a function, it helps to control the number of arguments to the functions. I think Robert Martin has a similar argument. When talking about functions in chapter 3 of <a href="">Clean Code</a>, his first section is about writing small functions and a later section about function arguments open by saying </p> <blockquote> The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification--and then shouldn't be used anyway. </blockquote> <p> In the C# code <code>a.Foo(b)</code>, <code>Foo</code> is an instance method that "feels" like it only has one argument. In reality, its two inputs are <code>a</code> and <code>b</code>, and that code uses infix notation. The situation is similar in the F# code <code>a |&gt; List.map f</code>. The function <code>List.map</code> (as well as the operator <code>|&gt;</code>) has two arguments and is applied using infix notation. I try to avoid creating functions that have more than two arguments. </p> <blockquote> I don't find the motivation given by jaco0646 convincing. If you have more than a handful of required parameters, I agree that that's an issue with complexity, but I don't agree that the solution is to add more complexity on top of it. Builders add complexity. </blockquote> <p> I am not sure how you are measuring complexity. I like to think that there are two types of complexity: local and global. For the sake of argument, let's suppose <ol> <li>that local complexity is only defined for a function and is the number of arguments of that function and <li>that global complexity is only defined for a entire program and is the number of lines in the program. </ol> I would argue that many required arguments is an issue of local complexity. We can decrease the local complexity at the expense of increasing the global complexity by replacing one function accepting many arguments with several functions accepting fewer arguments. I like to express this idea with the phrase "minimize the maximum (local) complexity". </p> <blockquote> ...you may also find <a href="https://blog.frankel.ch/builder-pattern-finite-state-machine">this article</a> [titled The Builder pattern is a finite state machine]...interesting. </blockquote> <p> Indeed, that is a nice article. Finite state machines/automata (both deterministic and nondeterministic) have the same expressiveness as regular expressions. </p> <blockquote> At a glance, though, with something like <code>Foo.WithA(a).WithB(b)</code> it seems to me that you're essentially reinventing <a href="https://en.wikipedia.org/wiki/Currying">currying</a> the hard way around. </blockquote> <p> It is. As a regular expression, it would be something like <code>AB</code>. I was just trying to give a simple example. The point of the article you shared is that the builder pattern is much more expressive. I have previously shared a <a href="https://blog.jooq.org/2012/01/05/the-java-fluent-api-designer-crash-course/">similar article</a>, but I like yours better. Thanks :) </p> <blockquote> ...you may also find...<a href="https://stackoverflow.com/a/2267467/126014">this Stack Overflow answer</a> interesting. </blockquote> <p> Wow. That is extremely cleaver! I would never thought of that. Thank you very much for sharing. </p> <blockquote> I'll be happy to give it a more formal treatment if there's reasonable scenario. Can you think of one? </blockquote> <p> As I said above, I often try to find ways to minimize the maximum complexity of the code that I write. In this case, the reason that I <a href="https://blog.ploeh.dk/2017/09/11/test-data-without-builders/#cb79773e74624514a1801af115f52f6b">originally asked you about the builder pattern</a> is that I was trying to improve the API for creating a binding in <a href="https://github.com/elmish/Elmish.WPF">Elmish.WPF</a>. The tutorial has a great <a href="https://github.com/elmish/Elmish.WPF/blob/master/TUTORIAL.md#the-elmishwpf-bindings">section about bindings</a>. There are many binding types, and each has multiple ways to create it. Most arguments are required and some are optional. </p> <p> <a href="https://github.com/elmish/Elmish.WPF/issues/87">Here</a> is a closed issue that was created during the transition to the current binding API, which uses method overloading. In an attempt to come up with a better API, <a href="https://github.com/elmish/Elmish.WPF/issues/87#issuecomment-530962855">I suggested</a> that we could use your suggestion to <a href="https://blog.ploeh.dk/2013/10/21/replace-overloading-with-discriminated-unions/">replace overloading with discriminated unions</a>, but my co-maintainer wasn't convinced that it would be better. </p> <p> Three days later, I increased the expressiveness of our bindings in <a href="https://github.com/elmish/Elmish.WPF/pull/118/files">this pull request</a>. Conceptually it was a small change; I added a single optional argument. For a regular expression, such a change is trivial. However, in my case it was a delta of +300 lines of mind-numbingly boring code. </p> <p> I agree with my co-maintainer that the current binding API is pretty good for the user. On the implementation side though, I am not satisfied. I want to find something better without sacrificing (and maybe even improving) the user's experience. </p> </div> <div class="comment-date">2020-03-16 04:03 UTC</div> </div> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Impureim sandwich https://blog.ploeh.dk/2020/03/02/impureim-sandwich 2020-03-02T07:03:00+00:00 Mark Seemann <div id="post"> <p> <em>Pronounced 'impurium sandwich'.</em> </p> <p> <a href="/2017/01/27/from-dependency-injection-to-dependency-rejection">Since January 2017</a> I've been singing the praise of the <em>impure/pure/impure</em> sandwich, but I've never published an article that defines the term. I intend this article to remedy the situation. </p> <h3 id="b1755f32e36d4a07b336d1b8fdc1b227"> Functional architecture <a href="#b1755f32e36d4a07b336d1b8fdc1b227" title="permalink">#</a> </h3> <p> In <a href="/2018/11/19/functional-architecture-a-definition">a functional architecture</a> <a href="https://en.wikipedia.org/wiki/Pure_function">pure functions</a> can't call impure actions. On the other hand, as <a href="https://en.wikipedia.org/wiki/Simon_Peyton_Jones">Simon Peyton Jones</a> observed in a lecture, <em>observing the result of pure computation is a side-effect</em>. In practical terms, <em>executing</em> a pure function is also impure, because it happens non-deterministically. Thus, even for a piece of software written in a functional style, the entry point must be impure. </p> <p> While pure functions can't call impure actions, there's no rule to prevent the obverse. Impure actions <em>can</em> call pure functions. </p> <p> Therefore, the best we can ever hope to achieve is an impure entry point that calls pure code and impurely reports the result from the pure function. </p> <p> <img src="/content/binary/impure-pure-impure-sandwich-box.png" alt="A box with a thin red slice on top, a thick green middle, and a thin red slice at the bottom."> </p> <p> The flow of code here goes from top to bottom: <ol> <li>Gather data from impure sources.</li> <li>Call a pure function with that data.</li> <li>Change state (including user interface) based on return value from pure function.</li> </ol> This is the <em>impure/pure/impure</em> sandwich. </p> <h3 id="c568a515c5a04024832079e491432bc4"> Metaphor <a href="#c568a515c5a04024832079e491432bc4" title="permalink">#</a> </h3> <p> The reason I call this a <em>sandwich</em> is that I think that it <em>looks</em> like a sandwich, albeit, perhaps, a rather tall one. According to the <a href="https://en.wikipedia.org/wiki/Sandwich">myth of the sandwich</a>, the <a href="https://en.wikipedia.org/wiki/John_Montagu,_4th_Earl_of_Sandwich">4th Earl of Sandwich</a> was a notorious gambler. While playing cards, he'd order two slices of bread with meat in between. This enabled him to keep playing without greasing the cards. His compatriots would order <em>the same as Sandwich</em>, or simply <em>a Sandwich</em>, and the name stuck. </p> <p> I like the sandwich as a metaphor. The bread is an <em>affordance</em>, in <a href="http://amzn.to/1NVqXQH">the spirit of Donald A. Norman</a>. It enables you to handle the meat without getting your fingers greased. In the same way, I think, impure actions enable you to handle a pure function. They let you invoke and observe the result of it. </p> <h3 id="0aa40b6f0f7c4648ac9a83f8fe2ab449"> Examples <a href="#0aa40b6f0f7c4648ac9a83f8fe2ab449" title="permalink">#</a> </h3> <p> One of the cleanest examples of an <em>impureim sandwich</em> remains <a href="/2017/02/02/dependency-rejection">my original article</a>: </p> <p> <pre><span style="color:#600277;">tryAcceptComposition</span>&nbsp;::&nbsp;<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;IO&nbsp;(Maybe&nbsp;Int) tryAcceptComposition&nbsp;reservation&nbsp;<span style="color:#666666;">=</span>&nbsp;runMaybeT&nbsp;<span style="color:#666666;">$</span> <span style="background-color: lightsalmon;">&nbsp;&nbsp;liftIO&nbsp;(<span style="color:#dd0000;">DB</span><span style="color:#666666;">.</span>readReservations&nbsp;connectionString&nbsp;<span style="color:#666666;">$</span>&nbsp;date&nbsp;reservation)</span> <span style="background-color: palegreen;">&nbsp;&nbsp;<span style="color:#666666;">&gt;&gt;=</span>&nbsp;<span style="color:#dd0000;">MaybeT</span>&nbsp;<span style="color:#666666;">.</span>&nbsp;return&nbsp;<span style="color:#666666;">.</span>&nbsp;flip&nbsp;(tryAccept&nbsp;<span style="color:#09885a;">10</span>)&nbsp;reservation</span> <span style="background-color: lightsalmon;">&nbsp;&nbsp;<span style="color:#666666;">&gt;&gt;=</span>&nbsp;liftIO&nbsp;<span style="color:#666666;">.</span>&nbsp;<span style="color:#dd0000;">DB</span><span style="color:#666666;">.</span>createReservation&nbsp;connectionString</span></pre> </p> <p> I've here repeated the code, but coloured the background of the impure, pure, and impure parts of the sandwich. </p> <p> I've shown plenty of other examples of this sandwich architecture, recently, for example, while <a href="/2019/12/02/refactoring-registration-flow-to-functional-architecture">refactoring a registration flow</a> in <a href="https://fsharp.org">F#</a>: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;sut&nbsp;pid&nbsp;r&nbsp;=&nbsp;async&nbsp;{ <span style="background-color: lightsalmon;">&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;validityOfProof&nbsp;=&nbsp;AsyncOption.traverse&nbsp;(twoFA.VerifyProof&nbsp;r.Mobile)&nbsp;pid</span> <span style="background-color: palegreen;">&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;decision&nbsp;=&nbsp;completeRegistrationWorkflow&nbsp;r&nbsp;validityOfProof</span> <span style="background-color: lightsalmon;">&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return!</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;decision &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;AsyncResult.traverseBoth&nbsp;db.CompleteRegistration&nbsp;twoFA.CreateProof &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;AsyncResult.cata&nbsp;(<span style="color:blue;">fun</span>&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;RegistrationCompleted)&nbsp;ProofRequired</span> &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> This last example looks as though the bottom part of the sandwich is larger then the rest of the composition. This can sometimes happen (and, in fact, last line of code is also pure). On the other hand, the pure part in the middle will typically <a href="/2019/12/09/put-cyclomatic-complexity-to-good-use">look like just a single line of code, even when the invoked function performs work of significant complexity</a>. </p> <p> The sandwich is a pattern independent of language. You can also <a href="/2019/02/11/asynchronous-injection">apply it in C#</a>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">async</span>&nbsp;<span style="color:#2b91af;">Task</span>&lt;<span style="color:#2b91af;">IActionResult</span>&gt;&nbsp;Post(<span style="color:#2b91af;">Reservation</span>&nbsp;reservation) { <span style="background-color: lightsalmon;">&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">await</span>&nbsp;Repository.ReadReservations(reservation.Date)</span> <span style="background-color: palegreen;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Select(rs&nbsp;=&gt;&nbsp;maîtreD.TryAccept(rs,&nbsp;reservation))</span> <span style="background-color: lightsalmon;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.SelectMany(m&nbsp;=&gt;&nbsp;m.Traverse(Repository.Create)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Match(InternalServerError(<span style="color:#a31515;">&quot;Table&nbsp;unavailable&quot;</span>),&nbsp;Ok);</span> }</pre> </p> <p> Like in the previous F# example, the final <code>Match</code> is most likely pure. In practice, <a href="/2020/02/24/discerning-and-maintaining-purity">you may not know</a>, because a method like <code>InternalServerError</code> or <code>Ok</code> is an inherited base class method. Regardless, I don't think that it's architecturally important, because what's going on there is rather trivial. </p> <h3 id="de8d05083dcd4dedae2b8b714702cc44"> Naming <a href="#de8d05083dcd4dedae2b8b714702cc44" title="permalink">#</a> </h3> <p> Since the metaphor occurred to me, I've been looking for a better name. The term <em>impure/pure/impure sandwich</em> seems too inconvenient, but nevertheless, people seem to have picked it up. </p> <p> I want a more distinct name, but have had trouble coming up with one. I've been toying with various abbreviations of <em>impure</em> and <em>pure</em>, but have finally settled on <em>impureim sandwich</em>. It's a contraction of <strong>im</strong>pure/<strong>pure</strong>/<strong>im</strong>pure. </p> <p> Why this particular contraction? </p> <p> I've played with lots of alternatives: <ul> <li>impureim: <strong>im</strong>pure/<strong>pure</strong>/<strong>im</strong>pure</li> <li>ipi: <strong>i</strong>mpure/<strong>p</strong>ure/<strong>i</strong>mpure</li> <li>impi: <strong>im</strong>pure/<strong>p</strong>ure/<strong>i</strong>mpure</li> <li>impim: <strong>im</strong>pure/<strong>p</strong>ure/<strong>im</strong>pure</li> </ul> and so on... </p> <p> I like <em>impureim</em> because the only <a href="https://en.wikipedia.org/wiki/Anagram">anagram</a> that I'm aware of is <em>imperium</em>. I therefore suggest that you pronounce it <em>impurium sandwich</em>. That'll work as a <a href="https://martinfowler.com/bliki/Neologism.html">neologic</a> <a href="https://en.wikipedia.org/wiki/Shibboleth">shibboleth</a>. </p> <h3 id="df74d63c013646aa9355b95e74fc3edc"> Summary <a href="#df74d63c013646aa9355b95e74fc3edc" title="permalink">#</a> </h3> <p> Functional architecture prohibits pure functions from invoking impure actions. On the other hand, a pure function is useless if you can't observe its result. A functional architecture, thus, must have an impure entry point that invokes a pure function and uses another impure action to act on the result. </p> <p> I suggest that we call such an <em>impure/pure/impure</em> interaction an <em>impureim sandwich</em>, and that we pronounce it an <em>impurium sandwich</em>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="4d71311250a54b1ca558a8469acdf445"> <div class="comment-author"><a href="https://massivepixel.co">Toni Petrina</a></div> <div class="comment-content"> <p> I find this example slightly simplistic. What happens when the logic has to do cascade reads/validations as it is typically done? Then you get impureimpureim...? Or do you fetch all data upfront even though it might be...irrelevant? For example, you want to send a comment to a blog post, but that post has forbidden new comments? Wouldn't you want to validate first and then fetch blog post if necessary? </p> </div> <div class="comment-date">2020-03-02 07:45 UTC</div> </div> <div class="comment" id="3cfe29c36690499cab429040260d818e"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Toni, thank you for writing. As I write <a href="/2019/12/02/refactoring-registration-flow-to-functional-architecture">in another article</a>, <blockquote> <p> "It's my experience that it's conspicuously often possible to implement an impure/pure/impure sandwich." </p> </blockquote> On the other hand, I never claimed that you can <em>always</em> do this. The impureim sandwich is a design pattern. It gives a name to a <a href="https://en.wikipedia.org/wiki/Software_design_pattern">general, reusable solution to a commonly occurring problem within a given context</a>. </p> <p> In cases where you can't apply the impureim sandwich pattern, <a href="/2017/07/10/pure-interactions">other patterns are available</a>. </p> </div> <div class="comment-date">2020-03-02 8:54 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Discerning and maintaining purity https://blog.ploeh.dk/2020/02/24/discerning-and-maintaining-purity 2020-02-24T07:31:00+00:00 Mark Seemann <div id="post"> <p> <em>Functional programming depends on referential transparency, but identifying and keeping functions pure requires deliberate attention.</em> </p> <p> <a href="https://en.wikipedia.org/wiki/Referential_transparency">Referential transparency</a> is the essence of functional programming. Most other traits that people associate with functional programming emerge from it: immutability, recursion, <a href="https://en.wikipedia.org/wiki/Higher-order_function">higher-order functions</a>, <a href="/2018/03/22/functors">functors</a> and monads, etcetera. </p> <p> To summarise, a <a href="https://en.wikipedia.org/wiki/Pure_function">pure function</a> has to obey two rules: <ul> <li>The same input always produces the same output.</li> <li>Calling it causes no side effects.</li> </ul> While those rules are easy to understand and remember, in practice they're harder to follow than most people realise. </p> <h3 id="8435839fae0b484399d4ada9f06e695d"> Lack of abstraction <a href="#8435839fae0b484399d4ada9f06e695d" title="permalink">#</a> </h3> <p> Mainstream programming languages don't distinguish between pure functions and impure actions. I'll use C# for examples, but you can draw the same conclusions for Java, C, C++, Visual Basic .NET and so on - even for <a href="https://fsharp.org">F#</a> and <a href="https://clojure.org">Clojure</a>. </p> <p> Consider this line of code: </p> <p> <pre><span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">validationMsg</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Validator</span>.<span style="color:#74531f;">Validate</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>);</pre> </p> <p> Is <code>Validate</code> a pure function? </p> <p> You might want to look at the method signature before you answer: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="color:#74531f;">Validate</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>)</pre> </p> <p> This is, unfortunately, not helpful. Will <code>Validate</code> always return the same <code>string</code> for the same <code>dto</code>? Can we guarantee that there's no side effects? </p> <p> You can't answer these questions only by examining the method signature. You'll have to go and <em>read</em> the code. </p> <p> This breaks <a href="/encapsulation-and-solid">encapsulation</a>. It ruins abstraction. It makes code harder to maintain. </p> <p> I can't stress this enough. This is what I've attempted to describe in my <a href="https://cleancoders.com/episode/humane-code-real-episode-1/show">Humane Code</a> video. We waste significant time <em>reading</em> existing code. Mostly because it's difficult to understand. It doesn't fit in our brains. </p> <p> <a href="http://amzn.to/19W4JHk">Agile Principles, Patterns, and Practices</a> defines an <em>abstraction</em> as <blockquote> <p> "the amplification of the essential and the elimination of the irrelevant" </p> <footer><cite>Robert C. Martin</cite></footer> </blockquote> This fits with the definition of encapsulation from <a href="http://amzn.to/1claOin">Object-Oriented Software Construction</a>. You should be able to interact with an object without knowledge of its implementation details. </p> <p> When you have to read the code of a method, it indicates a lack of abstraction and encapsulation. Unfortunately, that's the state of affairs when it comes to referential transparency in mainstream programming languages. </p> <h3 id="eabec7ed53c3482d86d1e4968101741f"> Manual analysis <a href="#eabec7ed53c3482d86d1e4968101741f" title="permalink">#</a> </h3> <p> If you read the source code of the <code>Validate</code> method, however, it's easy to figure out whether it's pure: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="color:#74531f;">Validate</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:blue;">_</span>)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; }</pre> </p> <p> Is the method deterministic? It seems like it. In fact, in order to answer that question, you need to know if <code>DateTime.TryParse</code> is deterministic. Assume that it is. Apart from the <code>TryParse</code> call, you can easily reason about the rest of this method. There's no randomness or other sources of non-deterministic behaviour in the method, so it seems reasonable to conclude that it's deterministic. </p> <p> Does the method produce side effects? Again, you have to know about the behaviour of <code>DateTime.TryParse</code>, but I think it's safe to conclude that there's no side effects. </p> <p> In other words, <code>Validate</code> is a pure function. </p> <h3 id="58667892c58f45ebac8e50946a9f1f2a"> Testability <a href="#58667892c58f45ebac8e50946a9f1f2a" title="permalink">#</a> </h3> <p> Pure functions are <a href="/2015/05/07/functional-design-is-intrinsically-testable">intrinsically testable</a> because they depend exclusively on their input. </p> <p> <pre>[<span style="color:#2b91af;">Fact</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">ValidDate</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ReservationDto</span>&nbsp;{&nbsp;Date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2021-12-21&nbsp;19:00&quot;</span>,&nbsp;Quantity&nbsp;=&nbsp;2&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Validator</span>.<span style="color:#74531f;">Validate</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">Empty</span>(<span style="font-weight:bold;color:#1f377f;">actual</span>); }</pre> </p> <p> This unit test creates a reservation <a href="https://en.wikipedia.org/wiki/Data_transfer_object">Data Transfer Object</a> (DTO) with a valid date string and a positive quantity. There's no error message to produce for a valid DTO. The test asserts that the error message is empty. It passes. </p> <p> You can with similar ease write a test that verifies what happens if you supply an invalid <code>Date</code> string. </p> <h3 id="de8e9b17b8c14448a76165337ebdc410"> Maintaining purity <a href="#de8e9b17b8c14448a76165337ebdc410" title="permalink">#</a> </h3> <p> The problem with manual analysis of purity is that any conclusion you reach only lasts until someone edits the code. Every time the code changes, you must re-evaluate. </p> <p> Imagine that you need to add a new validation rule. The system shouldn't accept reservations in the past, so you edit the <code>Validate</code> method: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="color:#74531f;">Validate</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">date</span>)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">$&quot;Invalid date: </span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">date</span>&nbsp;<span style="font-weight:bold;color:#74531f;">&lt;</span>&nbsp;<span style="color:#2b91af;">DateTime</span>.Now) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">$&quot;Invalid date: </span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; }</pre> </p> <p> Is the method still pure? No, it's not. It's now non-deterministic. One way to observe this is to let time pass. Assume that you wrote the above unit test well before December 21, 2021. That test still passes when you make the change, but months go by. One day (on December 21, 2021 at 19:00) the test starts failing. No code changed, but now you have a failing test. </p> <p> I've made sure that the examples in this article are simple, so that they're easy to follow. This could mislead you to think that the shift from referential transparency to impurity isn't such a big deal. After all, the test is easy to read, and it's clear why it starts failing. </p> <p> Imagine, however, that the code is as complex as the code base you work with professionally. A subtle change to a method deep in the bowels of a system can have profound impact on the entire architecture. You thought that you had a <a href="/2018/11/19/functional-architecture-a-definition">functional architecture</a>, but you probably don't. </p> <p> Notice that no types changed. The method signature remains the same. It's surprisingly difficult to maintain purity in a code base, even if you explicitly set out to do so. There's no <a href="https://en.wikipedia.org/wiki/Poka-yoke">poka-yoke</a> here; constant vigilance is required. </p> <h3 id="dcf2b00c3b4f49d192a10f0cb269d427"> Automation attempts <a href="#dcf2b00c3b4f49d192a10f0cb269d427" title="permalink">#</a> </h3> <p> When I explain these issues, people typically suggest some sort of annotation mechanism. Couldn't we use attributes to identify pure functions? Perhaps like this: </p> <p> <pre>[<span style="color:#2b91af;">Pure</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="color:#74531f;">Validate</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>)</pre> </p> <p> This doesn't solve the problem, though, because this still still compiles: </p> <p> <pre>[<span style="color:#2b91af;">Pure</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="color:#74531f;">Validate</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">date</span>)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">$&quot;Invalid date: </span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">date</span>&nbsp;<span style="font-weight:bold;color:#74531f;">&lt;</span>&nbsp;<span style="color:#2b91af;">DateTime</span>.Now) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">$&quot;Invalid date: </span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; }</pre> </p> <p> That's an impure action annotated with the <code>[Pure]</code> attribute. It still compiles and passes all tests (if you run them before December 21, 2021). The annotation is a lie. </p> <p> As I've already implied, you also have the compound problem that you need to know the purity (or lack thereof) of all APIs from the base library or third-party libraries. Can you be sure that no pure function becomes impure when you update a library from version 2.3.1 to 2.3.2? </p> <p> I'm not aware of any robust automated way to verify referential transparency in mainstream programming languages. </p> <h3 id="5413987a6af14316aee1b1de82aee73d"> Language support <a href="#5413987a6af14316aee1b1de82aee73d" title="permalink">#</a> </h3> <p> While no mainstream languages distinguish between pure functions and impure actions, there are languages that do. The most famous of these is <a href="https://www.haskell.org">Haskell</a>, but other examples include <a href="http://www.purescript.org">PureScript</a> and <a href="https://www.idris-lang.org">Idris</a>. </p> <p> I find Haskell useful for exactly that reason. The compiler enforces the functional interaction law. You can't call impure actions from pure functions. Thus, you wouldn't be able to make a change to a function like <code>Validate</code> without changing its type. That would break most consuming code, which is a good thing. </p> <p> You could write an equivalent to the original, pure version of <code>Validate</code> in Haskell like this: </p> <p> <pre><span style="color:#2b91af;">validateReservation</span>&nbsp;::&nbsp;<span style="color:blue;">ReservationDTO</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">Either</span>&nbsp;<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">ReservationDTO</span> validateReservation&nbsp;r@(ReservationDTO&nbsp;_&nbsp;d&nbsp;_&nbsp;_&nbsp;_)&nbsp;= &nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;readMaybe&nbsp;d&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;Nothing&nbsp;-&gt;&nbsp;Left&nbsp;$&nbsp;<span style="color:#a31515;">&quot;Invalid&nbsp;date:&nbsp;&quot;</span>&nbsp;++&nbsp;d&nbsp;++&nbsp;<span style="color:#a31515;">&quot;.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;Just&nbsp;(_&nbsp;::&nbsp;LocalTime)&nbsp;-&gt;&nbsp;Right&nbsp;r</pre> </p> <p> This is a pure function, because all Haskell functions are pure by default. </p> <p> You can change it to also check for reservations in the past, but only if you also change the type: </p> <p> <pre><span style="color:#2b91af;">validateReservation</span>&nbsp;::&nbsp;<span style="color:blue;">ReservationDTO</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;(<span style="color:#2b91af;">Either</span>&nbsp;<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">ReservationDTO</span>) validateReservation&nbsp;r@(ReservationDTO&nbsp;_&nbsp;d&nbsp;_&nbsp;_&nbsp;_)&nbsp;= &nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;readMaybe&nbsp;d&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;Nothing&nbsp;-&gt;&nbsp;<span style="color:blue;">return</span>&nbsp;$&nbsp;Left&nbsp;$&nbsp;<span style="color:#a31515;">&quot;Invalid&nbsp;date:&nbsp;&quot;</span>&nbsp;++&nbsp;d&nbsp;++&nbsp;<span style="color:#a31515;">&quot;.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;Just&nbsp;date&nbsp;-&gt;&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;utcNow&nbsp;&lt;-&nbsp;getCurrentTime &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;tz&nbsp;&lt;-&nbsp;getCurrentTimeZone &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;now&nbsp;=&nbsp;utcToLocalTime&nbsp;tz&nbsp;utcNow &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;date&nbsp;&lt;&nbsp;now &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:blue;">return</span>&nbsp;$&nbsp;Left&nbsp;$&nbsp;<span style="color:#a31515;">&quot;Invalid&nbsp;date:&nbsp;&quot;</span>&nbsp;++&nbsp;d&nbsp;++&nbsp;<span style="color:#a31515;">&quot;.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:blue;">return</span>&nbsp;$&nbsp;Right&nbsp;r</pre> </p> <p> Notice that I had to change the return type from <code>Either String ReservationDTO</code> to <code>IO (Either String ReservationDTO)</code>. The presence of <code>IO</code> marks the 'function' as impure. If I hadn't changed the type, the code simply wouldn't have compiled, because <code>getCurrentTime</code> and <code>getCurrentTimeZone</code> are impure actions. These types ripple through entire code bases, enforcing the functional interaction law at every level of the code base. </p> <h3 id="938b7dc2db644b6b94f6a484d65bb320"> Pure date validation <a href="#938b7dc2db644b6b94f6a484d65bb320" title="permalink">#</a> </h3> <p> How would you validate, then, that a reservation is in the future? In Haskell, like this: </p> <p> <pre><span style="color:#2b91af;">validateReservation</span>&nbsp;::&nbsp;<span style="color:blue;">LocalTime</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationDTO</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">Either</span>&nbsp;<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">ReservationDTO</span> validateReservation&nbsp;now&nbsp;r@(ReservationDTO&nbsp;_&nbsp;d&nbsp;_&nbsp;_&nbsp;_)&nbsp;= &nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;readMaybe&nbsp;d&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;Nothing&nbsp;-&gt;&nbsp;Left&nbsp;$&nbsp;<span style="color:#a31515;">&quot;Invalid&nbsp;date:&nbsp;&quot;</span>&nbsp;++&nbsp;d&nbsp;++&nbsp;<span style="color:#a31515;">&quot;.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;Just&nbsp;date&nbsp;-&gt; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;date&nbsp;&lt;&nbsp;now &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;Left&nbsp;$&nbsp;<span style="color:#a31515;">&quot;Invalid&nbsp;date:&nbsp;&quot;</span>&nbsp;++&nbsp;d&nbsp;++&nbsp;<span style="color:#a31515;">&quot;.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;Right&nbsp;r</pre> </p> <p> This function remains pure, although it still changes type. It now takes an additional <code>now</code> argument that represents the current time. You can retrieve the current time as an impure action before you call <code>validateReservation</code>. Impure actions can always call pure functions. This enables you to keep your complex domain model pure, which makes it simpler, and easier to test. </p> <p> Translated to C#, that corresponds to this version of <code>Validate</code>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="color:#74531f;">Validate</span>(<span style="color:#2b91af;">DateTime</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">now</span>,&nbsp;<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">date</span>)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">date</span>&nbsp;<span style="font-weight:bold;color:#74531f;">&lt;</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">now</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; }</pre> </p> <p> This version takes an additional <code>now</code> input parameter, but remains deterministic and free of side effects. Since it's pure, it's trivial to unit test. </p> <p> <pre>[<span style="color:#2b91af;">Theory</span>] [<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2010-01-01&nbsp;00:01&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2011-09-11&nbsp;18:30&quot;</span>,&nbsp;3)] [<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2019-11-26&nbsp;13:59&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2019-11-26&nbsp;19:00&quot;</span>,&nbsp;2)] [<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2030-10-02&nbsp;23:33&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2030-10-03&nbsp;00:00&quot;</span>,&nbsp;2)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">ValidDate</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">now</span>,&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservationDate</span>,&nbsp;<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">quantity</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ReservationDto</span>&nbsp;{&nbsp;Date&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">reservationDate</span>,&nbsp;Quantity&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">quantity</span>&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Validator</span>.<span style="color:#74531f;">Validate</span>(<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">Parse</span>(<span style="font-weight:bold;color:#1f377f;">now</span>),&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">Empty</span>(<span style="font-weight:bold;color:#1f377f;">actual</span>); }</pre> </p> <p> Notice that while the <code>now</code> parameter plays the <em>role</em> of the current time, the fact that it's just a value makes it trivial to run <em>simulations</em> of what would have happened if you ran this function in 2010, or what will happen when you run it in 2030. A test is really just a simulation by another name. </p> <h3 id="67101ecee7b94a849b24126ac01851fe"> Summary <a href="#67101ecee7b94a849b24126ac01851fe" title="permalink">#</a> </h3> <p> Most programming languages don't explicitly distinguish between pure and impure code. This doesn't make it impossible to do functional programming, but it makes it arduous. Since the language doesn't help you, you must constantly review changes to the code and its dependencies to evaluate whether code that's supposed to be pure remains pure. </p> <p> Tests can help, particularly if you employ <a href="/property-based-testing-intro">property-based testing</a>, but vigilance is still required. </p> <p> While Haskell isn't a mainstream programming language, I find that it helps me flush out my wrong assumptions about functional programming. I write many prototypes and proofs of concept in Haskell for that reason. </p> <p> Once you get the hang of it, it becomes easier to spot sources of impurity in other languages as well. <ul> <li>Anything with the <code>void</code> return type must be assumed to induce side effects.</li> <li>Everything that involves random numbers is non-deterministic.</li> <li>Everything that relies on the system clock is non-deterministic.</li> <li>Generating a GUID is non-deterministic.</li> <li>Everything that involves input/output is non-deterministic. That includes the file system and everything that involves network communication. In C# this implies that all <a href="/2016/04/11/async-as-surrogate-io">asynchronous APIs should be considered highly suspect</a>.</li> </ul> If you want to harvest the benefits of functional programming in a mainstream language, you must look out for such pitfalls. There's no tooling to assist you. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="1925963B8A194CF9BC44E0EB59E92C9C"> <div class="comment-author"><a href="http://criticalsoftwareblog.com">Yacoub Massad</a></div> <div class="comment-content"> <p> You might be interested in taking a look at <a href="https://github.com/ymassad/PurityAnalyzer">PurityAnalyzer</a>; An open source roslyn-based analyzer for C# that I started developing to help maintain pure C# code. </p> <p> Unfortunately, it is still not production-ready yet and I didn't have time to work on it in the last year. I was hoping contributors would help. </p> </div> <div class="comment-date">2020-02-24 08:16 UTC</div> </div> <div class="comment" id="50049d1906e04e1ab3811765ca5c3156"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Yacoub, thank you for writing. I wasn't aware of PurityAnalyzer. Do I understand it correctly that it's based mostly on a table of methods known (or assumed) to be pure? It also seems to look for certain attributes, under the assumption that if a <code>[Pure]</code> attribute is present, then one can trust it. Did I understand it correctly? </p> <p> The fundamental problems with such an approach aside, I can't think of a better solution for the current .NET platform. If you want contributors, though, you should edit the repository's readme-file so that it explains how the tool works, and how contributors could get involved. </p> </div> <div class="comment-date">2020-02-26 7:12 UTC</div> </div> <div class="comment" id="D45AAB9A9C2C4625BD949B2130416D79"> <div class="comment-author"><a href="http://criticalsoftwareblog.com">Yacoub Massad</a></div> <div class="comment-content"> <p >Here are the answers to your questions:</p> <p >1.it's based mostly on a table of methods known (or assumed) to be pure?</p> <p >This is true for compiled methods, e.g., methods in the .NET frameworks. There are lists maintained for .NET methods that are pure. The lists of course are still incomplete.</p> <p >For methods in the source code, the analyzer checks if they call impure methods, but it also checks other things like whether they access mutable state. The list of other things is not trivial. If you are interested in the details, see <a href="https://www.dotnetcurry.com/csharp/1464/pure-code-csharp"> this article</a>. It shows some of the details.</p> <p >2. It also seems to look for certain attributes, under the assumption that if a [Pure] attribute is present, then one can trust it. Did I understand it correctly?</p> <p >I don't use the [Pure] attribute because I think that the definition of pure used by Microsoft with this attribute is different than what I consider to be pure. I used a special [IsPure] attribute. There are also other attributes like [IsPureExceptLocally], [IsPureExceptReadLocally], [ReturnsNewObject], etc. The article I mentioned above explains some differences between these.</p> <p >I agree with you that I should work on readme file to explain details and ask for contributors.</p> </div> <div class="comment-date">2020-02-26 09:51 UTC</div> </div> <div class="comment" id="d28c24c07228400f9ed141f97b5c72b5"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> I love this post and enthusiastically agree with all the points you made. </p> <blockquote> Is the method deterministic? It seems like it. In fact, in order to answer that question, you need to know if <code>DateTime.TryParse</code> is deterministic. Assume that it is. </blockquote> <p> For what its worth, that <a href="https://referencesource.microsoft.com/#mscorlib/system/datetime.cs,1466">overload of <code>DateTime.TryParse</code></a> is impure because it depends on <a href="https://referencesource.microsoft.com/#mscorlib/system/globalization/datetimeformatinfo.cs,d8a79667802e6102"><code>DateTimeFormatInfo.CurrentInfo</code></a>, which depends on <a href="https://docs.microsoft.com/en-us/dotnet/api/system.threading.thread.currentculture?view=netframework-4.8#System_Threading_Thread_CurrentCulture"><code>System.Threading.Thread.CurrentThread.CurrentCulture</code></a>, which is mutable. </p> <blockquote> There are lists maintained for .NET methods that are pure. </blockquote> <p> Yacoub, could you share some links to such lists? </p> </div> <div class="comment-date">2020-02-26 20:14 UTC</div> </div> <div class="comment" id="d2cd79f75b0c4904bd55f34887513b61"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, I actually knew that, but in order to keep the example simple and compelling, I chose to omit that fact. That's why I phrased the sentence "<em>Assume</em> that it is" (my emphasis) 😉 </p> </div> <div class="comment-date">2020-02-26 21:56 UTC</div> </div> <div class="comment" id="CED4372686884B47B7FCC4CC03A50C47"> <div class="comment-author"><a href="http://criticalsoftwareblog.com">Yacoub Massad</a></div> <div class="comment-content"> <p> Tyson, I meant lists maintained as part of the PurityAnalyzer project. You can find them <a href="https://github.com/ymassad/PurityAnalyzer/tree/master/PurityAnalyzer/Resources">here</a>. </p> </div> <div class="comment-date">2020-02-27 07:48 UTC</div> </div> <div class="comment" id="0d0c85170c1c4062addf406f189c0984"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> The [Haskell] compiler enforces the functional interaction law. You can't call impure actions from pure functions. </blockquote> <p> And in contrast, the C# compiler does not enfore the functional interaction law, right? </p> <p> For exampe, suppose <code>Foo</code> and <code>Bar</code> are pure functions such that <code>Foo</code> calls <code>Bar</code> and the code compiles. Then only change the implementation of <code>Bar</code> in such a way that it is now impure and the code still compiles, which is possible. So <code>Foo</code> is now also impure as well, but its implementation didn't change. Therefore, the C# compiler does not enfore the functional interaction law. </p> <p> Is this consistent with what you mean by the functional interaction law? </p> </div> <div class="comment-date">2020-03-07 12:59 UTC</div> </div> <div class="comment" id="2d47bc8c9c07456091f923ea5298cd7e"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for writing. The C# compiler doesn't help protect your <em>intent</em>, if your intent is to apply a functional architecture. </p> <p> In your example, <code>Foo</code> starts out pure, but becomes impure. That's a <em>result</em> of the law. The law itself isn't broken, but the relationships change. That's often not what you want, so you can say that the compiler doesn't help you maintain a functional architecture. </p> <p> A compiler like Haskell protects the intent of the law. If <code>foo</code> (Haskell functions <em>must</em> start with a lower-case letter) and <code>bar</code> both start out pure, <code>foo</code> can call <code>bar</code>. When <code>bar</code> later becomes impure, its type changes and <code>foo</code> can no longer invoke it. </p> <p> I can try to express the main assertion of the functional interaction law like this: <em>a pure function can't call an impure action.</em> This has different implications in different compiler contexts. In Haskell, functions can be statically declared to be either pure or impure. This means that the Haskell compiler can prevent pure functions from calling impure actions. In C#, there's no such distinction at the type level. The implication is therefore different: that if <code>Foo</code> calls <code>Bar</code> and <code>Bar</code> is impure, then <code>Foo</code> must also be impure. This follows by elimination, because a pure function can't call an impure action. Therefore, since <code>Foo</code> <em>can</em> call <code>Bar</code>, and <code>Bar</code> is impure, then <code>Foo</code> must also be impure. </p> <p> The causation is reversed, so to speak. </p> <p> Does that answer your question? </p> </div> <div class="comment-date">2020-03-08 11:32 UTC</div> </div> <div class="comment" id="32759f1428c34fd0860e57c077df2972"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> Yes, that was a good answer. Thank you. </p> <blockquote> ...a pure function can't call an impure action. </blockquote> <p> We definitely want this to be true, but let's try to make sure it is. What do you think about the C# function <code>void Foo() =&gt; DateTime.Now;</code>? It has lots of good propertie: it alreays returns the same value (something isomorphic to <code>Unit</code>), and it does not mutate anything. However, it calls the impure property <code>DateTime.Now</code>. I think a reasonable person could argue that this function is pure. My guess is that you would say that it is impure. Am I right? I am willing to accept that. </p> <blockquote> ...a <a href="https://en.wikipedia.org/wiki/Pure_function">pure function</a> has to obey two rules: <ul> <li>The same input always produces the same output.</li> <li>Calling it causes no side effects.</li> </ul> </blockquote> <p> Is it possible for a function to violate the first rule but not violate the second rule? </p> </div> <div class="comment-date">2020-03-09 04:12 UTC</div> </div> <div class="comment" id="a7375c806c1147c1b37187834fb04153"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, I'm going to assume that you mean something like <code>void Foo() { var _ = DateTime.Now; }</code>, since the code you ask about doesn't compile 😉 </p> <p> That function is, indeed pure, because it has no observable side effects, and it always <a href="/2018/01/15/unit-isomorphisms">returns unit</a>. Purity is mostly a question of what we can observe if we consider the function a black box. </p> <p> Obviously, based on that criterion, we can refactor the function to <code>void Foo() { }</code> and we wouldn't be able to tell the difference. This version of <code>Foo</code> is clearly pure, although degenerate. <blockquote> Is it possible for a function to violate the first rule but not violate the second rule? </blockquote> Yes, the following method is non-deterministic, but has no side effects: <code>DateTime Foo() =&gt; DateTime.Now;</code> The input is always <em>unit</em>, but the return value can change. </p> </div> <div class="comment-date">2020-03-10 9:03 UTC</div> </div> <div class="comment" id="60eb2b1f83dd4b2fbc0be684d729af96"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> I think I need to practice test driven comment writing ;) Thanks for seeing through my syntax errors again. </p> <p> Oh, you think that that function is pure. Interesting. It follows then that the functional interaction law (pure functions cannot call impure actions) does <i>not</i> follow from the definition of a pure function. It is possible, in theory and in practice, for a pure function to call an impure action. Instead, the functional interaction law is "just" a goal to aspire to when designing a programming language. Haskell achieved that goal while C# and F# did not. Do you agree with this? (This is really what I was driving towards in <a href="https://blog.ploeh.dk/2020/02/24/discerning-and-maintaining-purity/#0d0c85170c1c4062addf406f189c0984">this comment above</a>, but I was trying to approach this "blasphemous" claim slowly.) </p> <p> Just as you helped me distinguish between function purity and totality in <a href="https://blog.ploeh.dk/2015/05/07/functional-design-is-intrinsically-testable/#97e4ae29436e4828813bf445ee1c37dc">this comment</a>, I think it would be helpful for us to consider separately the two defining properties of a pure function. The first property is "the same input always produces the same output". Let's call this weak determinism. <a href="https://en.wikipedia.org/wiki/Deterministic_algorithm">Determinism</a> is could be defined as "the same input always produces the same sequence of states", which includes the state of the output, so determinism is indeed stronger than weak determinism. The second property is "causes no side effect". It seems to me that there is either a lack of consensus or a lack of clarity about what constitutes a side effect. One definition I like is mutation of state outside of the current stack frame. </p> <p> One reason the functional interaction law is false in general is because the corresponding interaction law for weak determinism also false in general. The function I gave above (that called <code>DateTime.Now</code> and then returned unit) is a trivial example of that. A nontrivial example is <a href="https://en.wikipedia.org/wiki/Quicksort">quicksort</a>. </p> <p> At this point, I wanted to claim that the side effect interaction law is true in general, but it is not. This law says that a function that is side-effect free cannot call a function that causes a side effect. A counterexample is <code>void Foo() { int i = 0; Bar(ref i); }</code> with <code>void Bar(ref int i) => i++;</code>. That is, <code>Bar</code> mutates state outside of its stack frame, namely in the stack frame of <code>Foo</code>, so it is not side-effect free, but <code>Foo</code> is. (And I promise that I tested that code for compiler errors.) </p> <p> I need to think more about that. Is there a better definition of side effect, one for which the side effect interaction law is true? </p> <p> I just realized something that I think is interesting. Purely functional programming languages enforce a property of functions stronger than purity. With respect to the first defining property of a pure function (aka weak determinism), purely functional programming languages enforce the stronger notion of determinism. Otherwise, the compiler would need to realize that functions like quicksort should be allowed (because it is weakly deterministic). This reminds me of the debate between static and dynamic programming languages. In the process of forbidding certain unsafe code, static languages end up forbidding some safe code as well. </p> </div> <div class="comment-date">2020-03-10 14:05 UTC</div> </div> <div class="comment" id="dd776b1b8b0d43c58171ff7fec311c2c"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, I disagree with your basic premise: <blockquote> "It follows then that the functional interaction law (pure functions cannot call impure actions) does not follow from the definition of a pure function." </blockquote> I don't think that this follows. </p> <p> The key is that your example is <em>degenerate</em>. The <code>Foo</code> function is only pure because <code>DateTime.Now</code> isn't used. The actual, underlying property that we're aiming for is <a href="https://en.wikipedia.org/wiki/Referential_transparency">referential transparency</a>. Can you replace <code>Foo</code> with its value? Yes, you can. </p> <p> Perhaps you think this is a hand-wavy attempt to dodge a bullet, but I don't think that it is. You can write the equivalent function in Haskell like this: </p> <p> <pre><span style="color:#2b91af;">foo</span>&nbsp;::&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;() foo&nbsp;<span style="color:blue;">()</span>&nbsp;= &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;_&nbsp;=&nbsp;getCurrentTime &nbsp;&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:blue;">()</span></pre> </p> <p> I don't recall if you're familiar with Haskell, but for the benefit of any reader who comes by and wishes to follow this discussion, here are the important points: <ul> <li>The function calls <code>getCurrentTime</code>, which is an impure action. Its type is <code>IO UTCTime</code>. The <code>IO</code> <a href="https://bartoszmilewski.com/2014/01/14/functors-are-containers">container</a> marks the action as impure.</li> <li>The underscore is a <em>wildcard</em> that tells Haskell to discard the value.</li> <li>The type of <code>foo</code> is <code>() -&gt; ()</code>. It takes <a href="/2018/01/15/unit-isomorphisms">unit</a> as input and returns <em>unit</em>. There's no <code>IO</code> container involved, so the function is pure.</li> </ul> This works because Haskell is a strictly functional language. Every expression is referentially transparent. The implication is that something like <code>IO UTCTime</code> is an <em>opaque</em> container of <code>UTCTime</code> values. A pure caller can see the container, but not its contents. A common interpretation of this is that <code>IO</code> represents the superposition of all possible values, just like <a href="https://en.wikipedia.org/wiki/Schr%C3%B6dinger%27s_cat">Schrödinger's box</a>. Also, since Haskell is a lazily evaluated language, actions are only evaluated when their values are needed for something. Since the value of <code>getCurrentTime</code> is discarded, the impure action never runs (the box is never opened). This may be clearer with this example: </p> <p> <pre><span style="color:#2b91af;">bar</span>&nbsp;::&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;() bar&nbsp;<span style="color:blue;">()</span>&nbsp;= &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;_&nbsp;=&nbsp;<span style="color:blue;">putStrLn</span>&nbsp;<span style="color:#a31515;">&quot;Bar!&quot;</span> &nbsp;&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:blue;">()</span></pre> </p> <p> Like <code>foo</code>, <code>bar</code> calls an impure action: <code>putStrLn</code>, which corresponds to <code>Console.WriteLine</code>. Having the type <code>String -&gt; IO ()</code> it's impure. It works like this: </p> <p> <pre>&gt; putStrLn "Example" Example</pre> </p> <p> None the less, because <code>bar</code> discards the <code>IO ()</code> return value after it calls <code>putStrLn</code>, it never evaluates: </p> <p> <pre>&gt; bar () ()</pre> </p> <p> Perhaps a subtle rephrasing of the functional interaction law would be more precise. Perhaps it should say that a pure function can't <em>evaluate</em> an impure action. </p> <p> Bringing this back to C#, we have to keep in mind that C# doesn't enforce the functional interaction law in any way. Thus, the law works ex-post, instead of in Haskell, where it works ex-ante. Is the <code>Foo</code> C# code pure? Yes, it is, because it's referentially transparent. </p> <p> Regarding the purity of QuickSort, you may find <a href="https://stackoverflow.com/q/7717691/126014">this discussion</a> interesting. </p> </div> <div class="comment-date">2020-03-12 7:40 UTC</div> </div> <div class="comment" id="a06da27b57944c89aefc16914234939c"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> ...Haskell is a strictly functional language. Every expression is referentially transparent. ... Is the <code>Foo</code> C# code pure? Yes, it is, because it's referentially transparent. </blockquote> <p> So every function in Haskell is referentially transparent, and if a funciton in C# is referentially transparent, then it is pure. Is C# necessary there? Does referential transparency impliy purity regardless of langauge? Do you consider purity and referential transparency to be concepts that imply each other regulardless of language? I think a function is referential transparency if and only if it is pure, and I think this is independent of the langauge. </p> <p> If C# is not necessary, then it follows that every function in Haskell is pure. This seems like a contradiction with this statement. </p> <blockquote> The function calls <code>getCurrentTime</code>, which is an impure action. Its [return] type is <code>IO UTCTime</code>. The <code>IO</code> <a href="https://bartoszmilewski.com/2014/01/14/functors-are-containers">container</a> marks the action as impure. </blockquote> <p> You cited Bartosz Milewski there. <a href="https://www.schoolofhaskell.com/school/starting-with-haskell/basics-of-haskell/3-pure-functions-laziness-io#pure-functions">He also says</a> that every function in Haskell is pure. He calls Haskell functions returning IO a pure action. I agree with Milewski; I think every function in Haskell is pure. </p> <blockquote> Perhaps a subtle rephrasing of the functional interaction law would be more precise. Perhaps it should say that a pure function can't <em>evaluate</em> an impure action. </blockquote> <p> How does this rephrasing help? In the exmaple from my previous comment, <code>bar</code> is impure while <code>foo</code> is pure even though <code>foo</code> evaluates <code>bar</code>, which can be verified by putting a breakpoint in <code>bar</code> when evaluating <code>foo</code> or by observing that <code>i</code> has value <code>1</code> when <code>foo</code> returns. If Haskell contained impure functions, then replacing "calls" with "evalutes" helps because everything is lazy in Haskell, but I don't see how it helps in an eager langauge like C#. </p> <blockquote> Regarding the purity of QuickSort, you may find <a href="https://stackoverflow.com/q/7717691/126014">this discussion</a> interesting. </blockquote> <p> Oh, sorry. I now see that my reference to quicksort was unclear. I meant the randomized version of quicksort for the pivot is selected uniformily at random from all elements being sorted. That refrasing of the functional interaction law doesn't address the issue I am trying to point out with quicksort. To elborate, consider this randomized version of quicksort that has no side effects. I think this function is pure even though it uses randomness, which is necessarily obtained from an impure function. </p> </div> <div class="comment-date">2020-07-06 13:57 UTC</div> </div> <div class="comment" id="9f9664e29c3f4fafa786abae039eb20e"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, my apologies that I've been so dense. I think that I'm beginning to understand where you're going with this. Calling out randomised pivot selection in quicksort helped, I think. </p> <p> I would consider a quicksort function referentially transparent, even if it were to choose the pivot at random. Even if it does that, you can replace a given function call with its output. The only difference you might observe across multiple function calls would be varying execution time, due to lucky versus unlucky random pivot selection. Execution time is, however, not a property that impacts whether or not we consider a function pure. </p> <p> <em>Safe Haskell</em> can't do that, though, so you're correct when you say: <blockquote> "In the process of forbidding certain unsafe code, static languages end up forbidding some safe code as well." </blockquote> (Actually, you <em>can</em> implement quicksort like that in Haskell as well. In order to not muddy the waters, I've so far ignored that the language has an escape hatch for (among other purposes) this sort of scenario: <code>unsafePerformIO</code>. In <em>Safe Haskell</em>, however, you can't use it, and I've never myself had to use it.) </p> <p> I'm going to skip the discussion about whether or not all of Haskell is pure, because I think it's a red herring. We can discuss it later, if you're interested. </p> <p> I think that you're right, though, that the functional interaction law has to come with a disclaimer. I'm not sure exactly how to formulate it, but I need to take a detour around side effects, and then perhaps you can help me with that. </p> <p> Functional programmers know that every execution has side effects. In the extreme, running any calculation on a computer produces heat. There could be other side effects as well, such as CPU registers changing values, data moving in and out of processor caches, and so on. The question is: when do side effects become significant? </p> <p> We don't consider the generation of heat a significant side effect. What about a debug trace? If it doesn't affect the state of the system, does it count? If not, then how about logging or auditing? </p> <p> We usually draw the line somewhere and say that anything on one side counts, and things on the other side don't. The bottom line is, though, that we consider some side effects insignificant. </p> <p> I think that you have now demonstrated that there's symmetry. Not only are there insignificant side effects, but insignificant randomness also exists. The randomness involved in choosing a pivot in quicksort has no significant impact on the output. </p> <p> Was that what you meant by <em>weak determinism?</em> </p> </div> <div class="comment-date">2020-07-07 19:53 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Builder as a monoid https://blog.ploeh.dk/2020/02/17/builder-as-a-monoid 2020-02-17T07:18:00+00:00 Mark Seemann <div id="post"> <p> <em>Builder, particularly Fluent Builder, is one of the more useful design patterns. Here's why.</em> </p> <p> This article is part of <a href="/2018/03/05/some-design-patterns-as-universal-abstractions/">a series of articles about design patterns and their universal abstraction counterparts</a>. </p> <p> The <a href="https://en.wikipedia.org/wiki/Builder_pattern">Builder design pattern</a> is an occasionally useful pattern, but mostly in its Fluent Builder variation. I've already described that <a href="/2020/02/10/builder-isomorphisms">Builder, Fluent Builder, and Immutable Fluent Builder are isomorphic</a>. The Immutable Fluent Builder variation is a set of <a href="https://en.wikipedia.org/wiki/Pure_function">pure functions</a>, so among the three variations, it best fits the set of universal abstractions that I've so far discussed in <a href="/2017/10/04/from-design-patterns-to-category-theory">this article series</a>. </p> <p> <a href="http://amzn.to/XBYukB">Design Patterns</a> describes 23 patterns. Some of these are more useful than others. I first read the book in 2003, and while I initially used many of the patterns, after some years I settled into a routine where I'd reach for the same handful of patterns and ignore the rest. </p> <p> What makes some design patterns more universally useful than others? There's probably components of both subjectivity and chance, but I also believe that there's some correlation to universal abstractions. I consider abstractions universal when they are derived from universal truths (i.e. mathematics) instead of language features or 'just' experience. That's what the overall article series is about. In this article, you'll learn how the Builder pattern is an instance of a universal abstraction. Hopefully, this goes a long way towards explaining why it seems to be so universally useful. </p> <h3 id="6d834828809b4ac2b36f59bb244e5952"> Builder API, isolated <a href="#6d834828809b4ac2b36f59bb244e5952" title="permalink">#</a> </h3> <p> I'll start with the <code>HttpRequestMessageBuilder</code> from the article about <a href="/2020/02/10/builder-isomorphisms">Builder isomorphisms</a>, particularly its Immutable Fluent Builder incarnation. Start by isolating those methods that manipulate the Builder. These are the functions that had <code>void</code> return types in the original Builder incarnation. Imagine, for example, that you extract an interface of only those methods. What would such an interface look like? </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>); }</pre> </p> <p> Keep in mind that on all instance methods, <a href="/2018/02/12/object-isomorphisms">the instance itself can be viewed as 'argument 0'</a>. In that light, each of these methods take two arguments: a Builder and the formal argument (<code>jsonBody</code> and <code>newMethod</code>, respectively). Each method returns a Builder. I've <a href="/2019/01/28/better-abstractions-revisited#047886dcfa5a4a1398965138669e0ddc">already described how this is equivalent to an endomorphism</a>. An <a href="https://en.wikipedia.org/wiki/Endomorphism">endomorphism</a> is a function that returns the same type of output as its input, and <a href="/2017/11/13/endomorphism-monoid">it forms a monoid</a>. </p> <p> This can be difficult to see, so I'll make it explicit. The code that follows only exists to illustrate the point. In no way do I endorse that you write code in this way. </p> <h3 id="e022825850dc4fbf8d78b550bebb5d7c"> Explicit endomorphism <a href="#e022825850dc4fbf8d78b550bebb5d7c" title="permalink">#</a> </h3> <p> You can define a formal interface for an endomorphism: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">T</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">T</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="color:#2b91af;">T</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>); }</pre> </p> <p> Notice that it's completely generic. The <code>Run</code> method takes a value of the generic type <code>T</code> and returns a value of the type <code>T</code>. The identity of the <a href="/2017/10/06/monoids">monoid</a>, you may recall, is the eponymously named <em>identity</em> function which returns its input without modification. You can also define the monoidal combination of two endomorphisms: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">AppendEndomorphism</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;:&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">T</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;morphism1; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;morphism2; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">AppendEndomorphism</span>(<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism1</span>,&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism2</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.morphism1&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism1</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.morphism2&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism2</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">T</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="color:#2b91af;">T</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;morphism2.<span style="font-weight:bold;color:#74531f;">Run</span>(morphism1.<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="font-weight:bold;color:#1f377f;">x</span>)); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> This implementation of <code>IEndomorphism&lt;T&gt;</code> composes two other <code>IEndomorphism&lt;T&gt;</code> objects. When its <code>Run</code> method is called, it first calls <code>Run</code> on <code>morphism1</code> and then uses the return value of that method call (still a <code>T</code> object) as input for <code>Run</code> on <code>morphism2</code>. </p> <p> If you need to combine more than two endomorphisms then that's also possible, because <a href="/2017/11/20/monoids-accumulate">monoids accumulate</a>. </p> <h3 id="5f10f8e180b349a0b0584812a0c62431"> Explicit endomorphism to change HTTP method <a href="#5f10f8e180b349a0b0584812a0c62431" title="permalink">#</a> </h3> <p> You can adapt the <code>WithMethod</code> method to the <code>IEndomorphism&lt;HttpRequestMessageBuilder&gt;</code> interface: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">ChangeMethodEndomorphism</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;newMethod; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">ChangeMethodEndomorphism</span>(<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.newMethod&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">x</span>&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#1f377f;">x</span>)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>.<span style="font-weight:bold;color:#74531f;">WithMethod</span>(newMethod); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> In itself, this is simple code, but it does turn things on their head. The <code>newMethod</code> argument is now a class field (and constructor argument), while the <code>HttpRequestMessageBuilder</code> has been turned into a method argument. Keep in mind that I'm not doing this because I endorse this style of API design; I do it to demonstrate how the Immutable Fluent Builder pattern is an endomorphism. </p> <p> Since <code>ChangeMethodEndomorphism</code> is an <a href="https://en.wikipedia.org/wiki/Adapter_pattern">Adapter</a> between <code>IEndomorphism&lt;HttpRequestMessageBuilder&gt;</code> and the <code>WithMethod</code> method, I hope that this is becoming apparent. I'll show one more Adapter. </p> <h3 id="73a3f6e43a19457a937b36ed8682defa"> Explicit endomorphism to add a JSON body <a href="#73a3f6e43a19457a937b36ed8682defa" title="permalink">#</a> </h3> <p> In the example code, there's one more method that modifies an <code>HttpRequestMessageBuilder</code> object, and that's the <code>AddJsonBody</code> method. You can also create an Adapter over that method: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">AddJsonBodyEndomorphism</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">object</span>&nbsp;jsonBody; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">AddJsonBodyEndomorphism</span>(<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.jsonBody&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">x</span>&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#1f377f;">x</span>)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>.<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(jsonBody); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> While the <code>AddJsonBody</code> method itself is more complicated than <code>WithMethod</code>, the Adapter is strikingly similar. </p> <h3 id="680c696032f542ae8cddcf7a520e84eb"> Running an explicit endomorphism <a href="#680c696032f542ae8cddcf7a520e84eb" title="permalink">#</a> </h3> <p> You can use the <code>IEndomorphism&lt;T&gt;</code> API to compose a pipeline of operations that will, for example, make an <code>HttpRequestMessageBuilder</code> build an HTTP <code>POST</code> request with a JSON body: </p> <p> <pre><span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AppendEndomorphism</span>&lt;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&gt;( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ChangeMethodEndomorphism</span>(<span style="color:#2b91af;">HttpMethod</span>.Post), &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AddJsonBodyEndomorphism</span>(<span style="color:blue;">new</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;id&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">NewGuid</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2020-03-22&nbsp;19:30:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Ælfgifu&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;email&nbsp;=&nbsp;<span style="color:#a31515;">&quot;ælfgifu@example.net&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;quantity&nbsp;=&nbsp;1 &nbsp;&nbsp;&nbsp;&nbsp;}));</pre> </p> <p> You can then <code>Run</code> the endomorphism over a new <code>HttpRequestMessageBuilder</code> object to produce an HTTP request: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism</span>.<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>)).<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> The <code>msg</code> object represents an HTTP <code>POST</code> request with the supplied JSON body. </p> <p> Once again, I stress that the purpose of this little exercise is only to demonstrate how an Immutable Fluent Builder is an endomorphism, which is a monoid. </p> <h3 id="cfbf771a96144050ac21bf7c58333595"> Test Data Builder endomorphism <a href="#cfbf771a96144050ac21bf7c58333595" title="permalink">#</a> </h3> <p> You can give <a href="http://www.natpryce.com/articles/000714.html">Test Data Builders</a> the same treatment, again only to demonstrate that the reason they compose so well is because they're monoids. I'll use an immutable variation of the <code>AddressBuilder</code> from <a href="/2017/08/15/test-data-builders-in-c">this article</a>. </p> <p> For example, to modify a city, you can introduce an endomorphism like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">CityEndomorphism</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">AddressBuilder</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">string</span>&nbsp;city; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">CityEndomorphism</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">city</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.city&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">city</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="color:#2b91af;">AddressBuilder</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>.<span style="font-weight:bold;color:#74531f;">WithCity</span>(city); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> You can use it to create an address in Paris like this: </p> <p> <pre><span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">AddressBuilder</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">CityEndomorphism</span>(<span style="color:#a31515;">&quot;Paris&quot;</span>); <span style="color:#2b91af;">Address</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">address</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism</span>.<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>()).<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> The <code>address</code> is fully populated with <code>Street</code>, <code>PostCode</code>, and so on, but apart from <code>City</code>, you know none of the values. </p> <h3 id="c5d669df78134e22a5910233da2cc813"> Sweet spot <a href="#c5d669df78134e22a5910233da2cc813" title="permalink">#</a> </h3> <p> Let's return to the question from the introduction to the article. What makes some design patterns useful? I don't think that there's a single answer to that question, but I find it intriguing that so many of the useful patterns turn out to be equivalent to universal abstractions. The Builder pattern is a monoid. From a programming perspective, the most useful characteristic of <a href="/2017/11/27/semigroups">semigroups</a> and monoids is that they enable you to treat many objects as one object. Monoids compose. </p> <p> Of the three Builder variations, the Immutable Fluent Builder is the most useful. It's also the variation that most clearly corresponds to the endomorphism monoid. Viewing it as an endomorphism reveals its strengths. When or where is a Builder most useful? </p> <p> Don't be mislead by <em>Design Patterns</em>, which states the intent of the Builder pattern like this: <blockquote> <p> "Separate the construction of a complex object from its representation so that the same construction process can create different representations." </p> <footer><cite>Gamma et al, Design Patterns, 1994</cite></footer> </blockquote> This may still be the case, but I don't find that this is the primary advantage offered by the pattern. We've learned much about the utility of each design pattern since 1994, so I don't blame the Gang of Four for not seeing this. I do think, however, that it's important to emphasise that the benefit you can derive from a pattern may differ from the original motivation. </p> <p> An endomorphism represents a modification of a value. You need a value to get started, and you get a modified value (of the same type) as output. </p> <p> <img src="/content/binary/single-step-endomorphism.png" alt="An object (a little circle) to the left, going into a horizontally oriented pipe, and coming out to the right in a different colour."> </p> <p> Sometimes, all you need is the initial object. </p> <p> <img src="/content/binary/single-object-depicted-as-a-circle.png" alt="An object represented as a little circle."> </p> <p> And sometimes, you need to compose several changes. </p> <p> <img src="/content/binary/double-step-endomorphism.png" alt="An object (a little circle) to the left, going into two horizontally oriented pipe, on after the other, and coming out to the right in a different colour."> </p> <p> To me, this makes the sweet spot for the pattern clear. Use an (Immutable) Fluent Builder when you have a basic object that's useful in itself, but where you want to give client code the option to make changes to the defaults. </p> <p> Sometimes, the initial object has self-contained default values. Test Data Builders are good examples of that: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.street&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.city&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.postCode&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PostCodeBuilder</span>().<span style="font-weight:bold;color:#74531f;">Build</span>(); }</pre> </p> <p> The <code>AddressBuilder</code> constructor fully initialises the object. You can use its <code>WithNoPostcode</code>, <code>WithStreet</code>, etcetera methods to make changes to it, but you can also use it as is. </p> <p> In other cases, client code must initialise the object to be built. The <code>HttpRequestMessageBuilder</code> is an example of that: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Uri</span>(<span style="font-weight:bold;color:#1f377f;">url</span>))&nbsp;{&nbsp;} <span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:#2b91af;">HttpMethod</span>.Get,&nbsp;<span style="color:blue;">null</span>)&nbsp;{&nbsp;} <span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">method</span>,&nbsp;<span style="color:blue;">object</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.url&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>; &nbsp;&nbsp;&nbsp;&nbsp;Method&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">method</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.jsonBody&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>; }</pre> </p> <p> While there's more than one constructor overload, client code must supply a <code>url</code> in one form or other. That's the precondition of this class. Given a valid <code>url</code>, though, an <code>HttpRequestMessageBuilder</code> object can be useful without further modification, but you can also modify it by calling its methods. </p> <p> You often see the Builder pattern used for configuration APIs. The ASP.NET Core <a href="https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.iapplicationbuilder">IApplicationBuilder</a> is a prominent example of the Fluent Builder pattern. The <a href="https://docs.particular.net/samples/endpoint-configuration">NServiceBus endpoint configuration API</a>, on the other hand, is based on the classic Builder pattern. It makes sense to use an endomorphic design for framework configuration. Framework designers want to make it as easy to get started with their framework as possible. For this reason, it's important to provide a useful default configuration, so that you can get started with as little <a href="/2019/12/16/zone-of-ceremony">ceremony</a> as possible. On the other hand, a framework must be flexible. You need a way to tweak the configuration to support your particular needs. The Builder pattern supports both scenarios. </p> <p> Other examples include Test Data Builders, as well as specialised Builders such as <a href="https://docs.microsoft.com/dotnet/api/system.uribuilder">UriBuilder</a> and <a href="https://docs.microsoft.com/dotnet/api/system.data.sqlclient.sqlconnectionstringbuilder">SqlConnectionStringBuilder</a>. </p> <p> It's also worth noting that <a href="https://docs.microsoft.com/dotnet/fsharp/language-reference/copy-and-update-record-expressions">F# copy-and-update expressions</a> are endomorphisms. That's the reason that when you have immutable records, <a href="/2017/09/11/test-data-without-builders">you need no Test Data Builders</a>. </p> <h3 id="64b49f4143eb49fc80ab6344e247a0bd"> Summary <a href="#64b49f4143eb49fc80ab6344e247a0bd" title="permalink">#</a> </h3> <p> The Builder pattern comes in (at least) three variations: the Gang-of-Four Builder pattern, Fluent Builder, and Immutable Fluent Builder. All are isomorphic to each other, and are equivalent to the endomorphism monoid. </p> <p> Viewing Builders as endomorphisms may mostly be an academic exercise, but I think it highlights the sweet spot for the pattern. It's particularly useful when you wish to expose an API that offers simple defaults, while at the same time enabling client code to make changes to those defaults. When those changes involve several steps (as e.g. <code>AddJsonBody</code>) you can view each modifier method as a <a href="https://en.wikipedia.org/wiki/Facade_pattern">Facade</a>. </p> <p> <strong>Next:</strong> <a href="/2018/06/25/visitor-as-a-sum-type">Visitor as a sum type</a>. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Builder isomorphisms https://blog.ploeh.dk/2020/02/10/builder-isomorphisms 2020-02-10T07:06:00+00:00 Mark Seemann <div id="post"> <p> <em>The Builder pattern is equivalent to the Fluent Builder pattern.</em> </p> <p> This article is part of <a href="/2018/01/08/software-design-isomorphisms">a series of articles about software design isomorphisms</a>. An isomorphism is when a bi-directional lossless translation exists between two representations. Such translations exist between the <a href="https://en.wikipedia.org/wiki/Builder_pattern">Builder</a> pattern and two variations of the <em>Fluent Builder</em> pattern. Since the names sound similar, this is hardly surprising. </p> <p> <img src="/content/binary/builder-fluent-builder-isomorphism.png" alt="isomorphism between Builder, Fluent Builder, and Immutable Fluent Builder."> </p> <p> Given an implementation that uses one of those three patterns, you can translate your design into one of the other options. This doesn't imply that each is of equal value. When it comes to composability, both versions of Fluent Builder are superior to the classic Builder pattern. </p> <h3 id="553fdf908eb84ccb86a7c7972d45bc77"> A critique of the Maze Builder example <a href="#553fdf908eb84ccb86a7c7972d45bc77" title="permalink">#</a> </h3> <p> In these articles, I usually first introduce the form presented in <a href="http://amzn.to/XBYukB">Design Patterns</a>. The code example given by the Gang of Four is, however, problematic. I'll start by pointing out the problems and then proceed to present a simpler, more useful example. </p> <p> The book presents an example centred on a <code>MazeBuilder</code> abstract class. The original example is in C++, but I here present my C# interpretation: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">abstract</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">MazeBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">virtual</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BuildMaze</span>()&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">virtual</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BuildRoom</span>(<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">room</span>)&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">virtual</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BuildDoor</span>(<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">roomFrom</span>,&nbsp;<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">roomTo</span>)&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">virtual</span>&nbsp;<span style="color:#2b91af;">Maze</span>&nbsp;<span style="font-weight:bold;color:#74531f;">GetMaze</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">null</span>; &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> As the book states, "the maze-building operations of MazeBuilder do nothing by default. They're not declared pure virtual to let derived classes override only those methods in which they're interested." This means that you could technically write a derived class that overrides only <code>BuildRoom</code>. That's unlikely to be useful, since <code>GetMaze</code> still returns <code>null</code>. </p> <p> Moreover, the presence of the <code>BuildMaze</code> method indicates <a href="https://en.wikipedia.org/wiki/Sequential_coupling">sequential coupling</a>. A client (a <em>Director</em>, in the pattern language of <em>Design Patterns</em>) is supposed to first call <code>BuildMaze</code> before calling any of the other methods. What happens if a client forgets to call <code>BuildMaze</code>? What happens if client code calls the method <em>after</em> some of the other methods. What happens if it calls it multiple times? </p> <p> Another issue with the sample code is that it's unclear how it accomplishes its stated goal of separating "the construction of a complex object from its representation." The <code>StandardMazeBuilder</code> presented seems tightly coupled to the <code>Maze</code> class to a degree where it's hard to see how to untangle the two. The book fails to make a compelling example by instead presenting a <code>CountingMazeBuilder</code> that never implements <code>GetMaze</code>. It never constructs the desired complex object. </p> <p> Don't interpret this critique as a sweeping dismissal of the pattern, or the book in general. As this article series implies, I've invested significant energy in it. I consider the book seminal, but we've learned much since its publication in 1994. A common experience is that not all of the patterns in the book are equally useful, and of those that are, some are useful for different reasons than the book gives. The Builder pattern is an example of that. </p> <p> The Builder pattern isn't useful only because it enables you to "separate the construction of a complex object from its representation." It's useful because it enables you to present an API that comes with good default behaviour, but which can be tweaked into multiple configurations. The pattern is useful even without polymorphism. </p> <h3 id="ed99bc3715f541be8b6b9239848395e3"> HTTP request Builder <a href="#ed99bc3715f541be8b6b9239848395e3" title="permalink">#</a> </h3> <p> The <a href="https://docs.microsoft.com/dotnet/api/system.net.http.httprequestmessage">HttpRequestMessage</a> class is a versatile API with good default behaviour, but it can be a bit awkward if you want to make an HTTP request with a body and particular headers. You can often get around the problem by using methods like <a href="https://docs.microsoft.com/dotnet/api/system.net.http.httpclient.postasync">PostAsync</a> on <a href="https://docs.microsoft.com/dotnet/api/system.net.http.httpclient">HttpClient</a>, but sometimes you need to drop down to <a href="https://docs.microsoft.com/dotnet/api/system.net.http.httpclient.sendasync">SendAsync</a>. When that happens, you need to build your own <code>HttpRequestMessage</code> objects. A Builder can encapsulate some of that work. </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;url; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">object</span>?&nbsp;jsonBody; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Uri</span>(<span style="font-weight:bold;color:#1f377f;">url</span>))&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.url&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Method&nbsp;=&nbsp;<span style="color:#2b91af;">HttpMethod</span>.Get; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;Method&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;<span style="color:blue;">set</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.jsonBody&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Build</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>(Method,&nbsp;url); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">BuildBody</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BuildBody</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(jsonBody&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">json</span>&nbsp;=&nbsp;<span style="color:#2b91af;">JsonConvert</span>.<span style="color:#74531f;">SerializeObject</span>(jsonBody); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Content&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">StringContent</span>(<span style="font-weight:bold;color:#1f377f;">json</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Content.Headers.ContentType.MediaType&nbsp;=&nbsp;<span style="color:#a31515;">&quot;application/json&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> Compared to <em>Design Patterns'</em> example, <code>HttpRequestMessageBuilder</code> isn't polymorphic. It doesn't inherit from a base class or implement an interface. As I pointed out in my critique of the <code>MazeBuilder</code> example, polymorphism doesn't seem to be the crux of the matter. You could easily introduce a base class or interface that defines the <code>Method</code>, <code>AddJsonBody</code>, and <code>Build</code> members, but what would be the point? Just like the <code>MazeBuilder</code> example fails to present a compelling <em>second</em> implementation, I can't think of another useful implementation of a hypothetical <code>IHttpRequestMessageBuilder</code> interface. </p> <p> Notice that I dropped the <em>Build</em> prefix from most of the Builder's members. Instead, I reserved the word <code>Build</code> for the method that actually creates the desired object. This is consistent with most modern Builder examples I've encountered. </p> <p> The <code>HttpRequestMessageBuilder</code> comes with a reasonable set of default behaviours. If you just want to make a <code>GET</code> request, you can easily do that: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>); <span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>(); <span style="color:#2b91af;">HttpClient</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">client</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#74531f;">GetClient</span>(); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">response</span>&nbsp;=&nbsp;<span style="color:blue;">await</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">client</span>.<span style="font-weight:bold;color:#74531f;">SendAsync</span>(<span style="font-weight:bold;color:#1f377f;">msg</span>);</pre> </p> <p> Since you only call the <code>builder</code>'s <code>Build</code> method, but never any of the other members, you get the default behaviour. A <code>GET</code> request with no body. </p> <p> Notice that the <code>HttpRequestMessageBuilder</code> protects its invariants. It follows the maxim that you should never be able to put an object into an invalid state. Contrary to <em>Design Patterns'</em> <code>StandardMazeBuilder</code>, it uses its constructors to enforce an invariant. Regardless of what sort of <code>HttpRequestMessage</code> you want to build, it must have a URL. Both constructor overloads require all clients to supply one. (In order to keep the code example as simple as possible, I've omitted all sorts of precondition checks, like checking that <code>url</code> isn't null, that it's a valid URL, and so on.) </p> <p> If you need to make a <code>POST</code> request with a JSON body, you can change the defaults: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>); <span style="font-weight:bold;color:#1f377f;">builder</span>.Method&nbsp;=&nbsp;<span style="color:#2b91af;">HttpMethod</span>.Post; <span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">new</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;id&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">NewGuid</span>(), &nbsp;&nbsp;&nbsp;&nbsp;date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2020-03-22&nbsp;19:30:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Ælfgifu&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;email&nbsp;=&nbsp;<span style="color:#a31515;">&quot;ælfgifu@example.net&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;quantity&nbsp;=&nbsp;1&nbsp;}); <span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>(); <span style="color:#2b91af;">HttpClient</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">client</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#74531f;">GetClient</span>(); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">response</span>&nbsp;=&nbsp;<span style="color:blue;">await</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">client</span>.<span style="font-weight:bold;color:#74531f;">SendAsync</span>(<span style="font-weight:bold;color:#1f377f;">msg</span>);</pre> </p> <p> Other combinations of <code>Method</code> and <code>AddJsonBody</code> are also possible. You could, for example, make a <code>DELETE</code> request without a body by only changing the <code>Method</code>. </p> <p> This incarnation of <code>HttpRequestMessageBuilder</code> is cumbersome to use. You must first create a <code>builder</code> object and then mutate it. Once you've invoked its <code>Build</code> method, you rarely need the object any longer, but the <code>builder</code> variable is still in scope. You can address those usage issues by refactoring a Builder to a Fluent Builder. </p> <h3 id="38b145cd45674bd989ebd37ca92b40f6"> HTTP request Fluent Builder <a href="#38b145cd45674bd989ebd37ca92b40f6" title="permalink">#</a> </h3> <p> In the Gang of Four Builder pattern, no methods return anything, except the method that creates the object you're building (<code>GetMaze</code> in the <code>MazeBuilder</code> example, <code>Build</code> in the <code>HttpRequestMessageBuilder</code> example). It's always possible to refactor such a Builder so that the <code>void</code> methods return something. They can always return the object itself: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;Method&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">set</span>;&nbsp;} <span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>) { &nbsp;&nbsp;&nbsp;&nbsp;Method&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">this</span>; } <span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.jsonBody&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">this</span>; }</pre> </p> <p> Changing <code>AddJsonBody</code> is as easy as changing its return type and returning <code>this</code>. Refactoring the <code>Method</code> property is a bit more involved. It's a language feature of C# (and a few other languages) that classes can have properties, so this concern isn't general. In languages without properties, things are simpler. In C#, however, I chose to make the property setter private and instead add a method that returns <code>HttpRequestMessageBuilder</code>. Perhaps it's a little confusing that the name of the method includes the word <em>method</em>, but keep in mind that the method in question is an HTTP method. </p> <p> You can now create a <code>GET</code> request with a one-liner: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>).<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> You don't have to declare any <code>builder</code> variable to mutate. Even when you need to change the defaults, you can just start with a builder and keep on chaining method calls: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>.Post) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">new</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;id&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">NewGuid</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2020-03-22&nbsp;19:30:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Ælfgifu&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;email&nbsp;=&nbsp;<span style="color:#a31515;">&quot;ælfgifu@example.net&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;quantity&nbsp;=&nbsp;1&nbsp;}) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> This creates a <code>POST</code> request with a JSON message body. </p> <p> We can call this pattern <em>Fluent Builder</em> because this version of the Builder pattern has a <a href="https://www.martinfowler.com/bliki/FluentInterface.html">Fluent Interface</a>. </p> <p> This usually works well enough in practice, but is vulnerable to <a href="https://en.wikipedia.org/wiki/Aliasing_(computing)">aliasing</a>. What happens if you reuse an <code>HttpRequestMessageBuilder</code> object? </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">deleteMsg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>.Delete).<span style="font-weight:bold;color:#74531f;">Build</span>(); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">getMsg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> As the variable names imply, the programmer responsible for these three lines of code incorrectly believed that without the call to <code>WithMethod</code>, the <code>builder</code> will use its default behaviour when <code>Build</code> is called. The previous line of code, however, mutated the <code>builder</code> object. Its <code>Method</code> property remains <code>HttpMethod.Delete</code> until another line of code changes it! </p> <h3 id="a75c7962ece449f6b6161fe6ae7beb1e"> HTTP request Immutable Fluent Builder <a href="#a75c7962ece449f6b6161fe6ae7beb1e" title="permalink">#</a> </h3> <p> You can disarm the aliasing booby trap by making the Fluent Builder immutable. A good first step in that refactoring is making sure that all class fields are <code>readonly</code>: </p> <p> <pre><span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;url; <span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">object</span>?&nbsp;jsonBody;</pre> </p> <p> The <code>url</code> field was already marked <code>readonly</code>, so the change only applies to the <code>jsonBody</code> field. In addition to the class fields, don't forget any automatic properties: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;Method&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;}</pre> </p> <p> The <code>HttpMethod</code> property previously had a <code>private</code> setter, but this is now gone. It's also strictly read only. </p> <p> Now that all data is read only, the only way you can 'change' values is via a constructor. Add a constructor overload that receives all data and chain the other constructors into it: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Uri</span>(<span style="font-weight:bold;color:#1f377f;">url</span>))&nbsp;{&nbsp;} <span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:#2b91af;">HttpMethod</span>.Get,&nbsp;<span style="color:blue;">null</span>)&nbsp;{&nbsp;} <span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">method</span>,&nbsp;<span style="color:blue;">object</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.url&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>; &nbsp;&nbsp;&nbsp;&nbsp;Method&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">method</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.jsonBody&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>; }</pre> </p> <p> I'm usually not keen on allowing <code>null</code> arguments, but I made the all-encompassing constructor <code>private</code>. In that way, at least no client code gets the wrong idea. </p> <p> The optional modification methods can now only do one thing: return a new object: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(url,&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>,&nbsp;jsonBody); } <span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(url,&nbsp;Method,&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>); }</pre> </p> <p> The client code looks the same as before, but now you no longer have an aliasing problem: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">deleteMsg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>.Delete).<span style="font-weight:bold;color:#74531f;">Build</span>(); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">getMsg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> Now <code>deleteMsg</code> represents a <code>Delete</code> request, and <code>getMsg</code> truly represents a <code>GET</code> request. </p> <p> Since this variation of the Fluent Builder pattern is immutable, it's natural to call it an <em>Immutable Fluent Builder</em>. </p> <p> You've now seen how to refactor from Builder via Fluent Builder to Immutable Fluent Builder. If these three pattern variations are truly isomorphic, it should also be possible to move in the other direction. I'll leave it as an exercise for the reader to do this with the HTTP request Builder example. Instead, I will briefly discuss another example that starts at the Fluent Builder pattern. </p> <h3 id="87464a8b3f4d4922b3929c50e098c344"> Test Data Fluent Builder <a href="#87464a8b3f4d4922b3929c50e098c344" title="permalink">#</a> </h3> <p> A prominent example of the Fluent Builder pattern would be the set of all <a href="http://www.natpryce.com/articles/000714.html">Test Data Builders</a>. I'm going to use the example I've <a href="/2017/08/15/test-data-builders-in-c">already covered</a>. You can visit the previous article for all details, but in summary, you can, for example, write code like this: </p> <p> <pre><span style="color:#2b91af;">Address</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">address</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>().<span style="font-weight:bold;color:#74531f;">WithCity</span>(<span style="color:#a31515;">&quot;Paris&quot;</span>).<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> This creates an <code>Address</code> object with the <code>City</code> property set to <code>"Paris"</code>. The <code>Address</code> class comes with other properties. You can trust that the <code>AddressBuilder</code> gave them values, but you don't know what they are. You can use this pattern in unit tests when you need an <code>Address</code> in <a href="https://en.wikipedia.org/wiki/Paris">Paris</a>, but you don't care about any of the other data. </p> <p> In my previous article, I implemented <code>AddressBuilder</code> as a Fluent Builder. I did that in order to stay as true to <a href="http://www.natpryce.com">Nat Pryce</a>'s original example as possible. Whenever I use the Test Data Builder pattern in earnest, however, I use the immutable variation so that I avoid the aliasing issue. </p> <h3 id="4274fe6c008e41bd8d4e596b9cc11762"> Test Data Builder as a Gang-of-Four Builder <a href="#4274fe6c008e41bd8d4e596b9cc11762" title="permalink">#</a> </h3> <p> You can easily refactor a typical Test Data Builder like <code>AddressBuilder</code> to a shape more reminiscent of the Builder pattern presented in <em>Design Patterns</em>. Apart from the <code>Build</code> method that produces the object being built, change all other methods to <code>void</code> methods: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">string</span>&nbsp;street; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">string</span>&nbsp;city; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">PostCode</span>&nbsp;postCode; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.street&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.city&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.postCode&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PostCodeBuilder</span>().<span style="font-weight:bold;color:#74531f;">Build</span>(); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithStreet</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newStreet</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.street&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">newStreet</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithCity</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newCity</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.city&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">newCity</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithPostCode</span>(<span style="color:#2b91af;">PostCode</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newPostCode</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.postCode&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">newPostCode</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithNoPostcode</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.postCode&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PostCode</span>(); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Build</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:blue;">this</span>.street,&nbsp;<span style="color:blue;">this</span>.city,&nbsp;<span style="color:blue;">this</span>.postCode); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> You can still build a test address in Paris, but it's now more inconvenient. </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">addressBuilder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>(); <span style="font-weight:bold;color:#1f377f;">addressBuilder</span>.<span style="font-weight:bold;color:#74531f;">WithCity</span>(<span style="color:#a31515;">&quot;Paris&quot;</span>); <span style="color:#2b91af;">Address</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">address</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">addressBuilder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> You can still use multiple Test Data Builders to build more complex test data, but the classic Builder pattern doesn't compose well. </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">invoiceBuilder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InvoiceBuilder</span>(); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">recipientBuilder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">RecipientBuilder</span>(); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">addressBuilder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>(); <span style="font-weight:bold;color:#1f377f;">addressBuilder</span>.<span style="font-weight:bold;color:#74531f;">WithNoPostcode</span>(); <span style="font-weight:bold;color:#1f377f;">recipientBuilder</span>.<span style="font-weight:bold;color:#74531f;">WithAddress</span>(<span style="font-weight:bold;color:#1f377f;">addressBuilder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>()); <span style="font-weight:bold;color:#1f377f;">invoiceBuilder</span>.<span style="font-weight:bold;color:#74531f;">WithRecipient</span>(<span style="font-weight:bold;color:#1f377f;">recipientBuilder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>()); <span style="color:#2b91af;">Invoice</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">invoice</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">invoiceBuilder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> These seven lines of code creates an <code>Invoice</code> object with a address without a post code. Compare that with the Fluent Builder <a href="/2017/08/15/test-data-builders-in-c#de2e6fb74f6f4319a0fef86dcd9b839e">example in the previous article</a>. This is a clear example that while the variations are isomorphic, they aren't equally useful. The classic Builder pattern isn't as practical as one of the Fluent variations. </p> <p> You might protest that this variation of <code>AddressBuilder</code>, <code>InvoiceBuilder</code>, etcetera isn't equivalent to the Builder pattern. After all, the Builder shown in <em>Design Patterns</em> is polymorphic. That's really not an issue, though. Just extract an interface from the concrete builder: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IAddressBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Build</span>(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithCity</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newCity</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithNoPostcode</span>(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithPostCode</span>(<span style="color:#2b91af;">PostCode</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newPostCode</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithStreet</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newStreet</span>); }</pre> </p> <p> Make the concrete class implement the interface: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IAddressBuilder</span></pre> </p> <p> You could argue that this adds no value. You'd be right. This goes contrary to the <a href="http://www.codemanship.co.uk/parlezuml/blog/?postid=934">Reused Abstractions Principle</a>. I think that the same criticism applies to <em>Design Patterns</em>' original description of the pattern, as I've already pointed out. The utility in the pattern comes from how it gives client code good defaults that it can then tweak as necessary. </p> <h3 id="a1e866bafec74def9a66f5ba96a0cca4"> Summary <a href="#a1e866bafec74def9a66f5ba96a0cca4" title="permalink">#</a> </h3> <p> The Builder pattern was originally described in <em>Design Patterns</em>. Later, smart people like Nat Pryce figured out that by letting each mutating operation return the (mutated) Builder, such a Fluent API offered superior composability. A further improvement to the Fluent Builder pattern makes the Builder immutable in order to avoid aliasing issues. </p> <p> All three variations are isomorphic. Work that one of these variations afford is also afforded by the other variations. </p> <p> On the other hand, the variations aren't equally useful. Fluent APIs offer superior composability. </p> <p> <strong>Next:</strong> <a href="/2018/05/22/church-encoding">Church encoding</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="f3f59d590234452aa6a9cd7ba56779f0"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> <p> You can now[, with the fluent builder implementation,] create a <code>GET</code> request with a one-liner: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>).<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> </blockquote> <p> It is also possible to write that one-liner with the original (non-fluent) builder implementation. Did you mean to show how it is possible with the fluent builder implementation to create a <code>DELETE</code> request with a one-liner? You have such an example two code blocks later. </p> </div> <div class="comment-date">2020-02-25 02:18 UTC</div> </div> <div class="comment" id="c12cb112352645a293bc5ecaf7d9c9aa"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, you are, of course, right. The default behaviour could also have been a one-liner with the non-fluent design. Every other configuration, however, can't be a one-liner with the Gang-of-Four pattern, while it can in the Fluent guise. </p> </div> <div class="comment-date">2020-02-25 6:44 UTC</div> </div> <div class="comment" id="ecec868120f644c28381b188ee2e75e4"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> Among the example uses of your <code>HttpRequestMessageBuilder</code>, I see three HTTP verbs used: <code>GET</code>, <code>DELETE</code>, and <code>POST</code>. Furthermore, a body is added if and only if the method is <code>POST</code>. This matches my expectations gained from my limited experience doing web programming. If a <code>GET</code> or <code>DELETE</code> request had a body or if a <code>POST</code> request did not have a body, then I would suspect that such behavior was a bug. </p> <p> For the sake of a question that I would like to ask, let's suppose that a body must be added if and only if the method is <code>POST</code>. Under this assumption, <code>HttpRequestMessageBuilder</code> can create invalid messages. For example, it can create a <code>GET</code> request with a body, and it can create a <code>POST</code> request without a body. Under this assumption, how would you modify your design so that only valid messages can be created? </p> </div> <div class="comment-date">2020-02-25 14:34 UTC</div> </div> <div class="comment" id="1a3c2d6c7d484c5da92e49ce81c8755d"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for another inspiring question! It gives me a good motivation to write about polymorphic Builders. I'll try to address this question in a future article. </p> </div> <div class="comment-date">2020-03-02 8:40 UTC</div> </div> <div class="comment" id="484b7f2bd2714a2d8c08adece0955668"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, I've now attempted to answer your question in <a href="/2020/03/09/polymorphic-builder">a new article</a>. </p> </div> <div class="comment-date">2020-03-09 6:53 UTC</div> </div> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Non-exceptional averages https://blog.ploeh.dk/2020/02/03/non-exceptional-averages 2020-02-03T06:38:00+00:00 Mark Seemann <div id="post"> <p> <em>How do you code without exceptions? Here's one example.</em> </p> <p> Encouraging object-oriented programmers to <a href="https://hackernoon.com/the-throw-keyword-was-a-mistake-l9e532di">avoid throwing exceptions</a> is as fun as telling them to renounce null references. To be fair, exception-throwing is such an ingrained feature of C#, Java, C++, etcetera that it can be hard to see how to do without it. </p> <p> To be clear, I don't insist that you pretend that exceptions don't exist in languages that have them. I'm also <a href="https://eiriktsarpalis.wordpress.com/2017/02/19/youre-better-off-using-exceptions">not advocating that you catch all exceptions in order to resurface them as railway-oriented programming</a>. On the other hand, I do endorse the generally good advice that you shouldn't use exceptions for <a href="https://en.wikipedia.org/wiki/Control_flow">control flow</a>. </p> <p> What can you do instead? Despite <a href="https://fsharpforfunandprofit.com/posts/against-railway-oriented-programming">all the warnings against railway-oriented programming</a>, <a href="/2018/06/11/church-encoded-either">Either</a> is still a good choice for a certain kind of control flow. Exceptions are for <em>exceptional</em> situations, such as network partitions, running out of memory, disk failures, and so on. Many run-time errors are both foreseeable and preventable. Prefer code that prevents errors. </p> <p> There's a few ways you can do that. One of them is to protect invariants by enforcing pre-conditions. If you have a static type system, you can use the type system to prevent errors. </p> <h3 id="ccb791521ac0417f870a2fe4dac946c7"> Average duration <a href="#ccb791521ac0417f870a2fe4dac946c7" title="permalink">#</a> </h3> <p> How would you calculate the average of a set of durations? You might, for example, <a href="/2017/06/27/pure-times">need to calculate average duration of message handling for a polling consumer</a>. C# offers many built-in overloads of the <a href="https://docs.microsoft.com/dotnet/api/system.linq.enumerable.average">Average</a> extension method, but none that calculates the average of <a href="https://docs.microsoft.com/dotnet/api/system.timespan">TimeSpan</a> values. </p> <p> How would you write that method yourself? </p> <p> It's not a trick question. </p> <p> Based on my experience coaching development teams, this is a representative example: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>&nbsp;<span style="color:#74531f;">Average</span>(<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">TimeSpan</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;=&nbsp;<span style="color:#2b91af;">TimeSpan</span>.Zero; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">count</span>&nbsp;=&nbsp;0; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">in</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">+=</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">count</span>++; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">/</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">count</span>; }</pre> </p> <p> This gets the job done in most situations, but it has two error modes. It doesn't work if <code>timeSpans</code> is empty, and it doesn't work if it's infinite. </p> <p> When the input collection is empty, you'll be trying to divide by zero, which isn't allowed. How do you deal with that? Most programmers I've met just shrug and say: <em>don't call the method with an empty collection.</em> Apparently, it's your responsibility as the caller. You have to memorise that this particular <code>Average</code> method has that particular precondition. </p> <p> I don't think that's a professional position. This puts the burden on client developers. In a world like that, you have to learn by rote the preconditions of thousands of APIs. </p> <p> What can you do? You could add a <a href="https://en.wikipedia.org/wiki/Guard_(computer_science)">Guard Clause</a> to the method. </p> <h3 id="38f629930c7845c0af1c50c586dfcb82"> Guard Clause <a href="#38f629930c7845c0af1c50c586dfcb82" title="permalink">#</a> </h3> <p> Adding a Guard Clause doesn't really make the method much easier to reason about for client developers, but at least it protects an invariant. </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>&nbsp;<span style="color:#74531f;">Average</span>(<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">TimeSpan</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.<span style="font-weight:bold;color:#74531f;">Any</span>()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentOutOfRangeException</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#1f377f;">timeSpans</span>), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;Can&#39;t&nbsp;calculate&nbsp;the&nbsp;average&nbsp;of&nbsp;an&nbsp;empty&nbsp;collection.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;=&nbsp;<span style="color:#2b91af;">TimeSpan</span>.Zero; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">count</span>&nbsp;=&nbsp;0; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">in</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">+=</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">count</span>++; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">/</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">count</span>; }</pre> </p> <p> Don't get me wrong. I often write code like this because it makes it easier for me as a library developer to reason about the rest of the method body. On the other hand, it basically just replaces one run-time exception with another. Before I added the Guard Clause, calling <code>Average</code> with an empty collection would cause it to throw an <code>OverflowException</code>; now it throws an <code>ArgumentOutOfRangeException</code>. </p> <p> From client developers' perspective, this is only a marginal improvement. You're still getting no help from the type system, but at least the run-time error is a bit more informative. Sometimes, that's the best you can do. </p> <h3 id="3825bb6fb4db4cd28b9134763d202b3a"> Finite collections <a href="#3825bb6fb4db4cd28b9134763d202b3a" title="permalink">#</a> </h3> <p> The <code>Average</code> method has two preconditions, but we've only addressed one. The other precondition is that the input <code>timeSpans</code> must be finite. Unfortunately, this compiles: </p> <p> <pre><span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;<span style="font-weight:bold;color:#74531f;">InfinitelyRepeat</span>&lt;<span style="color:#2b91af;">T</span>&gt;(<span style="color:#2b91af;">T</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">while</span>&nbsp;(<span style="color:blue;">true</span>)&nbsp;<span style="font-weight:bold;color:#8f08c4;">yield</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>; } <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>(1,&nbsp;2,&nbsp;3,&nbsp;4); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">tss</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#74531f;">InfinitelyRepeat</span>(<span style="font-weight:bold;color:#1f377f;">ts</span>); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">avg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">tss</span>.<span style="font-weight:bold;color:#74531f;">Average</span>();</pre> </p> <p> Since <code>tss</code> infinitely repeats <code>ts</code>, the <code>Average</code> method call (theoretically) loops forever; in fact it quickly overflows because it keeps adding <code>TimeSpan</code> values together. </p> <p> Infinite collections aren't allowed. Can you make that precondition explicit? </p> <p> I don't know of a way to test that <code>timeSpans</code> is finite at run time, but I can change the input type: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>&nbsp;<span style="color:#74531f;">Average</span>(<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:#2b91af;">TimeSpan</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.<span style="font-weight:bold;color:#74531f;">Any</span>()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentOutOfRangeException</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#1f377f;">timeSpans</span>), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;Can&#39;t&nbsp;calculate&nbsp;the&nbsp;average&nbsp;of&nbsp;an&nbsp;empty&nbsp;collection.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;=&nbsp;<span style="color:#2b91af;">TimeSpan</span>.Zero; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">in</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">+=</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">/</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.Count; }</pre> </p> <p> Instead of accepting any <code>IEnumerable&lt;TimeSpan&gt;</code> as an input argument, I've now constrained <code>timeSpans</code> to an <code>IReadOnlyCollection&lt;TimeSpan&gt;</code>. <a href="https://docs.microsoft.com/dotnet/api/system.collections.generic.ireadonlycollection-1">This interface</a> has been in .NET since .NET 4.5 (<a href="/2013/07/20/linq-versus-the-lsp">I think</a>), but it lives a quiet existence. Few people know of it. </p> <p> It's just <code>IEnumerable&lt;T&gt;</code> with an extra constraint: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;:&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">T</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>&nbsp;Count&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} }</pre> </p> <p> The <code>Count</code> property strongly implies that the <code>IEnumerable&lt;T&gt;</code> is finite. Also, that the value is an <code>int</code> implies that the maximum size of the collection is 2,147,483,647. That's probably going to be enough for most day-to-day use. </p> <p> You can no longer pass an infinite stream of values to the <code>Average</code> method. It's simply not going to compile. That both communicates and protects the invariant that infinite collections aren't allowed. It also makes the implementation code simpler, since the method doesn't have to count the elements. That information is already available from <code>timeSpans.Count</code>. </p> <p> If a type can address one invariant, can it also protect the other? </p> <h3 id="b1464fa0dafc42838b6f7db24d8356c8"> Non-empty collection <a href="#b1464fa0dafc42838b6f7db24d8356c8" title="permalink">#</a> </h3> <p> You can change the input type again. Here I've used <a href="/2017/12/11/semigroups-accumulate">this NotEmptyCollection&lt;T&gt; implementation</a>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>&nbsp;<span style="color:#74531f;">Average</span>(<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">NotEmptyCollection</span>&lt;<span style="color:#2b91af;">TimeSpan</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.Head; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">in</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.Tail) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">+=</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">/</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.Count; }</pre> </p> <p> Now client code can no longer call the <code>Average</code> method with an empty collection. That's also not going to compile. </p> <p> You've replaced a run-time check with a compile-time check. It's now clear to client developers who want to call the method that they must supply a <code>NotEmptyCollection&lt;TimeSpan&gt;</code>, instead of just any <code>IReadOnlyCollection&lt;TimeSpan&gt;</code>. </p> <p> You can also simplify the implementation code: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>&nbsp;<span style="color:#74531f;">Average</span>(<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">NotEmptyCollection</span>&lt;<span style="color:#2b91af;">TimeSpan</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.<span style="font-weight:bold;color:#74531f;">Aggregate</span>((<span style="font-weight:bold;color:#1f377f;">x</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">y</span>)&nbsp;=&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>&nbsp;<span style="font-weight:bold;color:#74531f;">+</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">y</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">/</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.Count; }</pre> </p> <p> How do we know that <code>NotEmptyCollection&lt;T&gt;</code> contains at least one element? The constructor enforces that constraint: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">NotEmptyCollection</span>(<span style="color:#2b91af;">T</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">head</span>,&nbsp;<span style="color:blue;">params</span>&nbsp;<span style="color:#2b91af;">T</span>[]&nbsp;<span style="font-weight:bold;color:#1f377f;">tail</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">head</span>&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#1f377f;">head</span>)); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Head&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">head</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Tail&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">tail</span>; }</pre> </p> <p> But wait, there's a Guard Clause and a <code>throw</code> there! Have we even accomplished anything, or did we just move the <code>throw</code> around? </p> <h3 id="ef73390937dc4f88997c7d42496b591e"> Parse, don't validate <a href="#ef73390937dc4f88997c7d42496b591e" title="permalink">#</a> </h3> <p> A Guard Clause is a kind of validation. It validates that input fulfils preconditions. The problem with validation is that you have to repeat it in various different places. Every time you receive some data as an input argument, it may or may not have been validated. A receiving method can't tell. There's no flag on a string, or a number, or a collection, which is set when data has been validated. </p> <p> Every method that receives such an input will have to perform validation, just to be sure that the preconditions hold. This leads to validation code being duplicated over a code base. When you duplicate code, you later update it in most of the places it appears, but forget to update it in a few places. Even if you're meticulous, a colleague may not know about the proper way of validating a piece of data. This leads to bugs. </p> <p> As <a href="https://lexi-lambda.github.io">Alexis King</a> explains in her <a href="https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate">Parse, don’t validate</a> article, 'parsing' is the process of validating input of weaker type into a value of a stronger type. The stronger type indicates that validation has happened. It's like a Boolean flag that indicates that, yes, the data contained in the type has been through validation, and found to hold. </p> <p> This is also the case of <code>NotEmptyCollection&lt;T&gt;</code>. If you have an object of that type, you know that it has already been validated. You know that the collection isn't empty. Even if you think that it looks like we've just replaced one exception with another, that's not the point. The point is that we've replaced scattered and unsystematic validation code with a single verification step. </p> <p> You may still be left with the nagging doubt that I didn't really avoid throwing an exception. I think that the <code>NotEmptyCollection&lt;T&gt;</code> constructor strikes a pragmatic balance. If you look only at the information revealed by the type (i.e. what an <a href="https://en.wikipedia.org/wiki/Integrated_development_environment">IDE</a> would display), you'll see this when you program against the class: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">NotEmptyCollection</span>(<span style="color:#2b91af;">T</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">head</span>,&nbsp;<span style="color:blue;">params</span>&nbsp;<span style="color:#2b91af;">T</span>[]&nbsp;<span style="font-weight:bold;color:#1f377f;">tail</span>)</pre> </p> <p> While you could, technically, pass <code>null</code> as the <code>head</code> parameter, it should be clear to you that you're trying to do something you're not supposed to do: <code>head</code> is <em>not</em> an optional argument. Had it been optional, the API designer should have provided an overload that you could call without any value. Such a constructor overload isn't available here, so if you try to cheat the compiler by passing <code>null</code>, don't be surprised to get a run-time exception. </p> <p> For what it's worth, I believe that you can only be pragmatic if you know how to be dogmatic. Is it possible to protect <code>NotEmptyCollection&lt;T&gt;</code>'s invariants without throwing exceptions? </p> <p> Yes, you could do that by making the constructor <code>private</code> and instead afford a static factory method that returns a <a href="/2018/03/26/the-maybe-functor">Maybe</a> or <a href="/2018/06/11/church-encoded-either">Either</a> value. In <a href="https://www.haskell.org">Haskell</a>, this is typically called a <em>smart constructor</em>. It's only a few lines of code, so I could easily show it here. I chose not to, though, because I'm concerned that readers will interpret this article the wrong way. I like Maybe and Either a lot, but I agree with the above critics that it may not be <a href="/2015/08/03/idiomatic-or-idiosyncratic">idiomatic</a> in object-oriented languages. </p> <h3 id="737101b053e847f08124d49659804bf6"> Summary <a href="#737101b053e847f08124d49659804bf6" title="permalink">#</a> </h3> <p> <em>Encapsulation</em> is central to object-oriented design. It's the notion that it's an object's own responsibility to protect its invariants. In statically typed object-oriented programming languages, objects are instances of classes. Classes are types. Types encapsulate invariants; they carry with them guarantees. </p> <p> You can sometimes model invariants by using types. Instead of performing a run-time check on input arguments, you can declare constructors and methods in such a way that they only take arguments that are already guaranteed to be valid. </p> <p> That's one way to reduce the amount of exceptions that your code throws. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="127722bf00aa49c8aa467df2200028f6"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> Great post. I too prefer to avoid exceptions by strengthening preconditions using types. </p> <blockquote> Since <code>tss</code> infinitely repeats <code>ts</code>, the <code>Average</code> method call (theoretically) loops forever; in fact it quickly overflows because it keeps adding <code>TimeSpan</code> values together. </blockquote> <p> I am not sure what you mean here.  My best guess is that you are saying that this code would execute forever except that it will overflow, which will halt the execution.  However, I think the situation is ambiguous.  This code is impure because, as the <a href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/checked-and-unchecked">Checked and Unchecked documentation</a> says, its behavior depends on whether or not the <code>-checked</code> compiler option is given.  This dependency on the compiler option can be removed by wrapping this code in a <a href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/checked">checked</a> or <a href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/unchecked">unchecked</a> block, which would either result in a thrown exception or an infinite loop respectively. </p> <blockquote> This gets the job done in most situations, but it has two error modes. It doesn't work if <code>timeSpans</code> is empty, and it doesn't work if it's infinite. </blockquote> <p> There is a third error mode, and it exists in every implementation you gave.  The issue of overflow is not restricted to the case of infinitely many <code>TimeSpan</code>s.  It only takes two.  I know of or remember this bug as <a href="https://thebittheories.com/the-curious-case-of-binary-search-the-famous-bug-that-remained-undetected-for-20-years-973e89fc212">"the last binary search bug"</a>.  That article shows how to correctly compute the average of two integers without overflowing.  A correct implementation for computing the average of more than two integers is to map each element to a mixed fraction with the count as the divisor and then appropriately aggregate those values.  The implementation given in <a href="https://www.quora.com/How-can-I-compute-the-average-of-a-large-array-of-integers-without-running-into-overflow/answer/Mark-Gordon-6">this Quora answer</a> seems correct to me. </p> <p> I know all this is unrelated to the topic of your post, but I also know how much you prefer to use examples that avoid this kind of accidental complexity.  Me too!  However, I still like your example and can't think of a better one at the moment. </p> </div> <div class="comment-date">2020-02-05 14:13 UTC</div> </div> <div class="comment" id="0bf86e75e130497dbc8384a235f100f5"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for writing. Given an infinite stream of values, the method throws an <code>OverflowException</code>. This is because <code>TimeSpan</code> addition explicitly does that: </p> <p> <pre>&gt; <span style="color:#2b91af;">TimeSpan</span>.MaxValue&nbsp;<span style="font-weight:bold;color:#74531f;">+</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>(1) <span style="color:red">System.OverflowException: TimeSpan overflowed because the duration is too long. + System.TimeSpan.Add(System.TimeSpan) + System.TimeSpan.op_Addition(System.TimeSpan, System.TimeSpan)</span></pre> </p> <p> This little snippet from <em>C# Interactive</em> also illustrates the third error mode that I hadn't considered. Good point, that. </p> </div> <div class="comment-date">2020-02-06 6:47 UTC</div> </div> <div class="comment" id="d3727f9523f24793adb6c632d1a93a67"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> Ah, yes. You are correct. Thanks for pointing out my mistake. Another way to verify this is inspecting <a href="https://referencesource.microsoft.com/#mscorlib/system/timespan.cs,153"><code>TimeSpan.Add</code> in Mircosoft's reference source</a>. I should have done those checks before posting. Thanks again! </p> </div> <div class="comment-date">2020-02-06 13:33 UTC</div> </div> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. The Maître d' kata https://blog.ploeh.dk/2020/01/27/the-maitre-d-kata 2020-01-27T06:45:00+00:00 Mark Seemann <div id="post"> <p> <em>A programming kata.</em> </p> <p> I <a href="/2020/01/13/on-doing-katas">recently wrote about doing programming katas</a>. You can find katas in many different places. Some sites exist exclusively for that purpose, such as the <a href="http://bit.ly/codekatas">Coding Dojo</a> or <a href="http://codekata.com">CodeKata</a>. In other cases, you can find individual katas on blogs; one of my favourites is the <a href="http://claysnow.co.uk/recycling-tests-in-tdd">Diamond kata</a>. You can also lift exercises from other sources and treat them as katas. For example, I recently followed <a href="https://github.com/mikehadlow/Journeys">Mike Hadlow's lead</a> and <a href="/2019/10/28/a-basic-haskell-solution-to-the-robot-journeys-coding-exercise">turned a job applicant test into a programming exercise</a>. I've also taken exercises from books and repurposed them. For example, <a href="/2017/10/23/convex-hull-monoid">I've implemented the Graham Scan algorithm for finding convex hulls</a> a couple of times. </p> <p> In this article, I'll share an exercise that I've found inspiring myself. I'll call it <em>the Ma&icirc;tre d' kata</em>. </p> <p> I present no code in this article. Part of what makes the exercise interesting, I think, is to figure out how to model the problem domain. I will, however, later publish one of my attempts at the kata. </p> <h3 id="73c0d7c81c1047d598cb6dbc8a49c99b"> Problem statement <a href="#73c0d7c81c1047d598cb6dbc8a49c99b" title="permalink">#</a> </h3> <p> Imagine that you're developing an online restaurant reservation system. Part of the behaviour of such a system is to decide whether or not to accept a reservation. At a real restaurant, employees fill various roles required to make it work. In a high-end restaurant, the <a href="https://en.wikipedia.org/wiki/Ma%C3%AEtre_d%27h%C3%B4tel">ma&icirc;tre d'</a> is responsible for taking reservations. I've named the kata after this role. If you're practising <a href="https://en.wikipedia.org/wiki/Domain-driven_design">domain-driven design</a>, you might want to name your object, class, or module <code>Ma&icirc;treD</code> or some such. </p> <p> The objective of the exercise is to implement the <code>Ma&icirc;treD</code> decision logic. </p> <p> Reservations are accepted on a first-come, first-served basis. As long as the restaurant has available seats for the desired reservation, it'll accept it. </p> <p> A reservation contains, at a minimum, a date and time as well as a positive quantity. Here's some examples: <table> <thead> <tr> <td>Date</td> <td style="text-align:right">Quantity</td> </tr> </thead> <tbody> <tr> <td>August 8, 2050 at 19:30</td> <td style="text-align:right">3</td> </tr> <tr> <td>November 27, 2022 at 18:45</td> <td style="text-align:right">4</td> </tr> <tr> <td>February 27, 2014 at 13:22</td> <td style="text-align:right">12</td> </tr> </tbody> </table> </p> <p> Notice that dates can be in your future or past. You might want to assume that the ma&icirc;tre d' would reject reservations in the past, but you can't assume <em>when</em> the code runs (or ran), so don't worry about that. Notice also that quantities are positive integers. While a quantity shouldn't be negative or zero, it could conceivably be large. I find it realistic, however, to keep quantities at low two-digit numbers or less. </p> <p> A reservation will likely contain other data, such as the name of the person making the reservation, contact information such as email or phone number, possibly also an ID, and so on. You may add these details if you want to make the exercise more realistic, but they're not required. </p> <p> I'm going to present one feature requirement at a time. If you read the entire article before you do the exercise, it'd correspond to gathering detailed requirements before starting to code. Alternatively, you could read the first requirement, do the exercise, read the next requirement, refactor your code, and so on. This would simulate a situation where your organisation gradually uncovers how the system ought to work. </p> <h3 id="f538ee06b5c54215bae10f661385893c"> Boutique restaurant <a href="#f538ee06b5c54215bae10f661385893c" title="permalink">#</a> </h3> <p> As readers of <a href="/dippp">my book</a> may have detected, I'm a foodie. Some years ago I ate at <a href="https://www.blancanyc.com">Blanca</a> in Brooklyn. That restaurant has one communal bar where everyone sits. There was room for twelve people, and dinner started at 19:00 whether you arrived on time or not. Such restaurants actually exist. It's an easy first step for the kata. Assume that the restaurant is only open for dinner, has no second seating, and a single shared table. This implies that the time of day of reservations doesn't matter, while the date still matters. Some possible test cases could be: <table> <thead> <tr> <td style="text-align:right">Table size</td> <td>Existing reservations</td> <td>Candidate reservation</td> <td>Expected outcome</td> </tr> </thead> <tbody> <tr> <td style="text-align:right">12</td> <td><em>none</em></td> <td>Quantity: 1</td> <td>Accepted</td> </tr> <tr> <td style="text-align:right">12</td> <td><em>none</em></td> <td>Quantity: 13</td> <td>Rejected</td> </tr> <tr> <td style="text-align:right">12</td> <td><em>none</em></td> <td>Quantity: 12</td> <td>Accepted</td> </tr> <tr> <td style="text-align:right">4</td> <td>Quantity: 2, Date: 2023-09-14</td> <td>Quantity: 3, Date: 2023-09-14</td> <td>Rejected</td> </tr> <tr> <td style="text-align:right">10</td> <td>Quantity: 2, Date: 2023-09-14</td> <td>Quantity: 3, Date: 2023-09-14</td> <td>Accepted</td> </tr> <tr> <td style="text-align:right">10</td> <td> Quantity: 3, Date: 2023-09-14<br> Quantity: 2, Date: 2023-09-14<br> Quantity: 3, Date: 2023-09-14 </td> <td>Quantity: 3, Date: 2023-09-14</td> <td>Rejected</td> </tr> <tr> <td style="text-align:right">4</td> <td>Quantity: 2, Date: 2023-09-15</td> <td>Quantity: 3, Date: 2023-09-14</td> <td>Accepted</td> </tr> </tbody> </table> </p> <p> This may not be an exhaustive set of test cases, but hopefully illustrates the desired behaviour. Try using the <a href="/2019/10/07/devils-advocate">Devil's Advocate technique</a> or <a href="/property-based-testing-intro">property-based testing</a> to identify more test cases. </p> <h3 id="05f0ec26d90044288845f5ad308742c2"> Haute cuisine <a href="#05f0ec26d90044288845f5ad308742c2" title="permalink">#</a> </h3> <p> The single-shared-table configuration is unusual. Most restaurants have separate tables. High-end restaurants like those on the <a href="https://www.theworlds50best.com">World's 50 best</a> list, or those with <a href="https://en.wikipedia.org/wiki/Michelin_Guide">Michelin stars</a> often have only a single seating. This is a good expansion of the domain logic. </p> <p> Assume that a restaurant has several tables, perhaps of different sizes. A table for four will seat one, two, three, or four people. Once a table is reserved, however, all the seats at that table are reserved. A reservation for three people will occupy a table for four, and the redundant seat is wasted. Obviously, the restaurant wants to maximise the number of guests, so it'll favour reserving two-person tables for one and two people, four-person tables for three and four people, and so on. </p> <p> In order to illustrate the desired behaviour, here's some extra test cases to add to the ones already in place: <table> <thead> <tr> <td>Tables</td> <td>Existing reservations</td> <td>Candidate reservation</td> <td>Expected outcome</td> </tr> </thead> <tbody> <tr> <td> Two tables for two<br> Two tables for four </td> <td><em>none</em></td> <td>Quantity: 4, Date: 2024-06-07</td> <td>Accepted</td> </tr> <tr> <td> Two tables for two<br> Two tables for four </td> <td><em>none</em></td> <td>Quantity: 5, Date: 2024-06-07</td> <td>Rejected</td> </tr> <tr> <td> Two tables for two<br> One table for four </td> <td>Quantity: 2, Date: 2024-06-07</td> <td>Quantity: 4, Date: 2024-06-07</td> <td>Accepted</td> </tr> <tr> <td> Two tables for two<br> One table for four </td> <td>Quantity: 3, Date: 2024-06-07</td> <td>Quantity: 4, Date: 2024-06-07</td> <td>Rejected</td> </tr> </tbody> </table> </p> <p> Again, you should consider adding more test cases if you're unit-testing the kata. </p> <h3 id="e008d27660b54882816e2e496ee89709"> Second seatings <a href="#e008d27660b54882816e2e496ee89709" title="permalink">#</a> </h3> <p> Some restaurants (even some of those on the <em>World's 50 best</em> list) have a second seating. As a diner, you have a limited time (e.g. 2&frac12; hours) to complete your meal. After that, other guests get your table. </p> <p> This implies that you must now consider the time of day of reservations. You should also be able to use an arbitrary (positive) seating duration. All previous rules should still apply. New test cases include: <table> <thead> <tr> <td>Seating duration</td> <td>Tables</td> <td>Existing reservations</td> <td>Candidate reservation</td> <td>Expected outcome</td> </tr> </thead> <tbody> <tr> <td>2 hours</td> <td> Two tables for two<br> One table for four </td> <td>Quantity: 4, Date: 2023-10-22, Time: 18:00</td> <td>Quantity: 3, Date: 2023-10-22, Time: 20:00</td> <td>Accepted</td> </tr> <tr> <td>2&frac12; hours</td> <td> One table for two<br> Two tables for four </td> <td> Quantity: 2, Date: 2023-10-22, Time: 18:00<br> Quantity: 1, Date: 2023-10-22, Time: 18:15<br> Quantity: 2, Date: 2023-10-22, Time: 17:45 </td> <td>Quantity: 3, Date: 2023-10-22, Time: 20:00</td> <td>Rejected</td> </tr> <tr> <td>2&frac12; hours</td> <td> One table for two<br> Two tables for four </td> <td> Quantity: 2, Date: 2023-10-22, Time: 18:00<br> Quantity: 2, Date: 2023-10-22, Time: 17:45 </td> <td>Quantity: 3, Date: 2023-10-22, Time: 20:00</td> <td>Accepted</td> </tr> <tr> <td>2&frac12; hours</td> <td> One table for two<br> Two tables for four </td> <td> Quantity: 2, Date: 2023-10-22, Time: 18:00<br> Quantity: 1, Date: 2023-10-22, Time: 18:15<br> Quantity: 2, Date: 2023-10-22, Time: 17:45 </td> <td>Quantity: 3, Date: 2023-10-22, Time: 20:15</td> <td>Accepted</td> </tr> </tbody> </table> </p> <p> If you make the seating duration short enough, you may even make room for a third seating, and so on. </p> <h3 id="cec332ae8ea444de929c2f5ca5603e90"> Alternative table configurations <a href="#cec332ae8ea444de929c2f5ca5603e90" title="permalink">#</a> </h3> <p> If tables are rectangular, the restaurant has the option to combine several smaller tables into one larger. Consider a typical restaurant layout like this: </p> <p> <img src="/content/binary/restaurant-configuration-with-three-individual-two-person-tables.png" alt="A map of a restaurant including three adjacent two-person tables."> </p> <p> There's a round four-person table, as well as a few small tables that can't easily be pushed together. There's also three (orange) two-person tables where one guest sits against the wall, and the other diner faces him or her. These can be used as shown above, but the restaurant can also push two of these tables together to accommodate four people: </p> <p> <img src="/content/binary/restaurant-configuration-with-two-two-person-tables-combined.png" alt="A map of a restaurant where two of the three adjacent two-person tables have been pushed together."> </p> <p> This still leaves one of the adjacent two-person tables as an individual table, but the restaurant can also push all three tables together to accommodate six people: </p> <p> <img src="/content/binary/restaurant-configuration-with-all-two-person-tables-combined.png" alt="A map of a restaurant where all three adjacent two-person tables have been pushed together."> </p> <p> Implement decision logic that allows for alternative table configurations. Remember to take seating durations into account. Consider both the configuration illustrated, as well as other configurations. Note that in the above configuration, not all two-person tables can be combined. </p> <h3 id="fa8d74d3a39f462ca23818f79eefb7a8"> More domain logic <a href="#fa8d74d3a39f462ca23818f79eefb7a8" title="permalink">#</a> </h3> <p> You can, if you will, invent extra rules. For example, restaurants have opening hours. A restaurant that opens at 18:00 and closes at 0:00 will not accept reservations for 13:30, regardless of table configuration, existing reservations, seating duration, and so on. </p> <p> Building on that idea, some restaurants have different opening hours on various weekdays. Some are closed Mondays, serve dinner only Tuesday to Friday, but are then open for both lunch and dinner in the weekend. </p> <p> Going in that direction, however, opens a can of worms. Perhaps the restaurant is closed on public holidays. Or perhaps it's explicitly open on public holidays, to cater for an audience that may not otherwise dine out. <a href="/2017/04/24/simple-holidays">But implementing a holiday calender is far from as simple as it sounds</a>. That's the reason I left such rules out of the above specifications of the kata. </p> <p> Another idea that you may consider is to combine communal bar seating with more traditional tables. <a href="https://thecloveclub.com">The Clove Club</a> is an example of restaurant that does it that way. </p> <h3 id="66b7a3d1b3e5453ca343494ccd0bc51a"> Summary <a href="#66b7a3d1b3e5453ca343494ccd0bc51a" title="permalink">#</a> </h3> <p> This is a programming kata description. Implement the decision logic of a ma&icirc;tre d': <em>Can the restaurant accept a given reservation?</em> </p> <p> After some time has gone by, I'll post at least one of my own attempts. You're welcome to <a href="https://github.com/ploeh/ploeh.github.com#comments">leave a comment</a> if you do the kata and wish to share your results. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Algebraic data types aren't numbers on steroids https://blog.ploeh.dk/2020/01/20/algebraic-data-types-arent-numbers-on-steroids 2020-01-20T07:39:00+00:00 Mark Seemann <div id="post"> <p> <em>A common red herring in the type debate.</em> </p> <p> I regularly get involved in debates about static versus dynamic typing. This post isn't an attempt to persuade anyone that static types are better. One of the reasons that I so often find myself debating this topic is that it intrigues me. I get the impression that most of the software luminaries that I admire (e.g. <a href="https://en.wikipedia.org/wiki/Kent_Beck">Kent Beck</a>, <a href="https://en.wikipedia.org/wiki/Robert_C._Martin">Robert C. Martin</a>, <a href="https://www.r7krecon.com/michael-feathers-bio">Michael Feathers</a>) seem to favour dynamically typed languages. What is it that smart people have figured out that I haven't? </p> <p> The debate continues, and this article isn't going to stop it. It may, perhaps, put one misconception to rest. There are still good arguments on either side. It's not my goal to dispute any of the good arguments. It's my goal to counter a common bad argument. </p> <h3 id="41cff26ef5fe4a56943d34da2e7ad657"> Misconception: static typing as numbers on steroids <a href="#41cff26ef5fe4a56943d34da2e7ad657" title="permalink">#</a> </h3> <p> I get the impression that many people think about static types as something that has to do with strings and numbers - particularly numbers. Introductions to programming languages often introduce strings first. That's natural, since the most common first example is <a href="https://en.wikipedia.org/wiki/%22Hello,_World!%22_program">Hello, world!</a>. After that usually follows an introduction to basic arithmetic, and that often includes an explanation about types of numbers - at least the distinction between integers and floating-point numbers. At the time I'm writing this, <a href="https://docs.microsoft.com/dotnet/csharp/tutorials/">the online C# tutorial</a> is a typical example of this. <a href="http://bit.ly/real-world-haskell">Real World Haskell</a> takes the same approach to introducing types. </p> <p> It's a natural enough way to introduce static types, but it seems to leave some learners with the impression that static types are mostly useful to prevent them from calling a method with a floating-point number when an integer was expected. That's the vibe I'm getting from <a href="https://blog.cleancoder.com/uncle-bob/2017/01/13/TypesAndTests.html">this article by Robert C. Martin</a>. </p> <p> When presented with the notion of a 'stronger' type system, people with that mindset seem to extrapolate what they already know about static types. </p> <p> <img src="/content/binary/extrapolation-of-static-primitive-types.png" alt="Three boxes, from left to right: no types, static primitive types, and static primitive types on steroids."> </p> <p> If you mostly think of static types as a way to distinguish between various primitive types (such as strings and a zoo of number types), I can't blame you for extrapolating that notion. This seems to happen often, and it leads to a lot of frustration. </p> <p> People who want 'stronger numbers' try to: <ul> <li>Model natural numbers; i.e. to define a type that represents only positive integers</li> <li>Model positive numbers; i.e. rational or real numbers greater than zero</li> <li>Model non-negative numbers</li> <li>Model numbers in a particular range; e.g. between 0 and 100</li> <li><a href="https://ren.zone/articles/safe-money">Model money in different currencies</a></li> </ul> Particularly, people run into all sorts of trouble when they try to accomplish such goals with <a href="https://www.haskell.org">Haskell</a>. They've heard that Haskell has a powerful type system, and now they want to do those things. </p> <p> Haskell does have a powerful type system, but it's a type system that builds on the concept of <a href="https://en.wikipedia.org/wiki/Algebraic_data_type">algebraic data types</a>. (If you want to escape the jargon of that Wikipedia article, I recommend <a href="http://tomasp.net">Tomas Petricek</a>'s lucid and straightforward explanation <a href="http://tomasp.net/blog/types-and-math.aspx">Power of mathematics: Reasoning about functional types</a>.) </p> <p> There are type systems that enable you to take the notion of numbers to the next level. This is called either <a href="https://en.wikipedia.org/wiki/Refinement_type">refinement types</a> or <a href="https://en.wikipedia.org/wiki/Dependent_type">dependent types</a>, contingent on what exactly it is that you want to do. Haskell doesn't support that out of the box. The most prominent dependently-typed programming language is probably <a href="https://www.idris-lang.org">Idris</a>, which is still a research language. As far as I know, there's no 'production strength' languages that support refinement or dependent types, unless you consider <a href="https://en.wikipedia.org/wiki/Liquid_Haskell">Liquid Haskell</a> to fit that description. Honestly, all this is at the fringe of my expertise. </p> <p> I'll return to an example of this kind of frustration later, and also suggest a simple alternative. Before I do that, though, I'd like to outline what it is proponents of 'strong' type systems mean. </p> <h3 id="76b0c9b8e461448796d44443351619f1"> Make illegal states unrepresentable <a href="#76b0c9b8e461448796d44443351619f1" title="permalink">#</a> </h3> <p> Languages like Haskell, <a href="https://ocaml.org">OCaml</a>, and <a href="https://fsharp.org">F#</a> have algebraic type systems. They still distinguish between various primitive types, but they take the notion of static types in a completely different direction. They introduce a new dimension of static type safety, so to speak. </p> <p> <img src="/content/binary/algebraic-data-types-as-another-dimension.png" alt="Three boxes. At the bottom left: no types. To the right of that: static primitive types. To the top of the no-types box: algebraic data types"> </p> <p> It's a completely different way to think about static types. The advantage isn't that it prevents you from using a floating point where an integer was required. The advantage is that it enables you to model domain logic in a way that flushes out all sorts of edge cases at compile time. </p> <p> I've previously <a href="/2016/11/28/easy-domain-modelling-with-types">described a real-world example of domain modelling with types</a>, so I'm not going to repeat that effort here. Most business processes can be described as a progression of states. With algebraic data types, not only can you model what a valid state looks like - you can also model the state machine in such a way that you can't represent illegal states. </p> <p> This notion is eloquently captured by the aphorism: <blockquote> <p> Make illegal states unrepresentable. </p> <footer><cite><a href="https://youtu.be/-J8YyfrSwTk">Yaron Minsky</a></cite></footer> </blockquote> This is solving an entirely different type of problem than distinguishing between 32-bit and 64-bit integers. Writing even moderately complex code involves dealing with many edge cases. In most mainstream languages (including C# and Java), it's your responsibility to ensure that you've handled all edge cases. It's easy to overlook or forget a few of those. With algebraic data types, the compiler keeps track of that for you. That's a tremendous boon because it enables you to forget about those technical details and instead focus on adding value. </p> <p> Scott Wlaschin wrote <a href="https://amzn.to/2OyI51M">an entire book about domain modelling with algebraic data types</a>. That's what we talk about when we talk about stronger type systems. Not 'numbers on steroids'. </p> <h3 id="4c5ac4aa723f4f078d5cfbb13164194c"> Exhibit: summing notionals <a href="#4c5ac4aa723f4f078d5cfbb13164194c" title="permalink">#</a> </h3> <p> I consider this notion of <em>strong type systems viewed as numbers on steroids</em> a red herring. I don't blame anyone from extrapolating from what they already know. That's a natural way to try to make sense of the world. We all do it. </p> <p> I came across a recent example of this way of thinking in a great article by <a href="https://alexnixon.github.io">Alex Nixon</a> titled <a href="https://alexnixon.github.io/2020/01/14/static-types-are-dangerous.html">Static types are dangerously interesting</a>. The following is in no way meant to excoriate Alex or his article, but I think it's a great example of how easily one can be lead astray by thinking that strong type systems imply numbers on steroids. </p> <p> You should read the article. It's well-written and uses more sophisticated features of Haskell than I'm comfortable with. The example problem it tries to solve is basically this: Given a set of trades, calculate the <em>total notional in each currency</em>. Consider a collection of trades: </p> <p> <pre>Quantity, Ticker, Price, Currency 100, VOD.L, 1, GBP 200, VOD.L, 2, GBP 300, AAPL.O, 3, USD 50, 4151.T, 5, JPY</pre> </p> <p> I'll let Alex explain what it is that he wants to do: <blockquote> <p> "I want to write a function which calculates the <em>total notional in each currency</em>. The word <em>notional</em> is a fancy way of saying <code>price * quantity</code>. Think of it as "value of the thing that changed hands". </p> <p> "For illustration, the function signature might look something like this: </p> <p> "<code>sumNotionals :: [Trade] -> Map Currency Rational</code> </p> <p> "In English, it’s a function that takes a list of trades and returns a map from currency to quantity." </p> </blockquote> If given the above trades, the output would be: </p> <p> <pre>Currency, Notional GBP, 500 USD, 900 JPY, 250</pre> </p> <p> The article proceeds to explore how to model this problem with Haskell's strong type system. Alex wants to be able to calculate with money, but on the other hand, he wants the type system to prevent accidents. You can't add <em>100 GBP</em> to <em>300 USD</em>. The type system should prevent that. </p> <p> Early on, he defines a <a href="https://en.wikipedia.org/wiki/Tagged_union">sum type</a> to model currencies: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;Currency &nbsp;&nbsp;=&nbsp;USD &nbsp;&nbsp;|&nbsp;GBP &nbsp;&nbsp;|&nbsp;JPY &nbsp;&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#2b91af;">Eq</span>,&nbsp;<span style="color:#2b91af;">Ord</span>,&nbsp;<span style="color:#2b91af;">Show</span>)</pre> </p> <p> Things basically go downhill from there. Read the article; it's good. </p> <h3 id="f04845b0c38f4924a5d34d1d5802912e"> Sum types should distinguish behaviour, not values <a href="#f04845b0c38f4924a5d34d1d5802912e" title="permalink">#</a> </h3> <p> I doubt that Alex Nixon views his proposed <code>Currency</code> type as anything but a proof of concept. In a 'real' code base, you'd enumerate all the currencies you'd trade, right? </p> <p> I wouldn't. This is the red herring in action. Algebraic data types are useful because they enable us to distinguish between cases that we should treat differently, by writing specific code that deals with each case. That's not the case with a currency. You add US dollars together in exactly the same way that you add euros together. The currency doesn't change the behaviour of that operation. </p> <p> But we can't just enable addition of arbitrary monetary values, right? After all, we shouldn't be able to add <em>20 USD</em> and <em>300 DKK</em>. At least, without an exchange rate, that shouldn't compile. </p> <p> Let's imagine, for the sake of argument, that we encode all the currencies we trade into a type. What happens if our traders decide to trade a currency that they haven't previously traded? What if a country decides to <a href="https://en.wikipedia.org/wiki/Redenomination">reset their currency</a>? What if a country splits into two countries, each with <a href="https://en.wikipedia.org/wiki/South_Sudanese_pound">their own currency</a>? </p> <p> If you model currency as a type, you'd have to edit and recompile your code every time such an external event occurs. I don't think this is a good use of a type system. </p> <p> Types should, I think, help us programmers identify the parts of our code bases where we need to treat various cases differently. They shouldn't be used to distinguish run-time values. Types provide value at compile time; run-time values only exist at run time. To paraphrase Kent Beck, <em>keep things together that change together; keep things apart that don't</em>. </p> <p> I'd model currency as a run-time value, because the behaviour of money doesn't vary with the currency. </p> <h3 id="cfa838f3fad84259b9629f24f09f37eb"> Boring Haskell <a href="#cfa838f3fad84259b9629f24f09f37eb" title="permalink">#</a> </h3> <p> How would I calculate the notionals, then? With <a href="https://www.snoyman.com/blog/2019/11/boring-haskell-manifesto">boring Haskell</a>. Really boring Haskell, in fact. I'm only going to need two imports and no language pragmas: </p> <p> <pre><span style="color:blue;">module</span>&nbsp;Trades&nbsp;<span style="color:blue;">where</span> <span style="color:blue;">import</span>&nbsp;Data.List <span style="color:blue;">import</span>&nbsp;Data.Map.Strict&nbsp;(<span style="color:blue;">Map</span>) <span style="color:blue;">import</span>&nbsp;<span style="color:blue;">qualified</span>&nbsp;Data.Map.Strict&nbsp;<span style="color:blue;">as</span>&nbsp;Map</pre> </p> <p> Which types do I need? For this particular purpose, I think I'll just stick with a single <code>Trade</code> type: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;Trade&nbsp;=&nbsp;Trade&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;tradeQuantity&nbsp;::&nbsp;Int &nbsp;&nbsp;,&nbsp;tradeTicker&nbsp;::&nbsp;String &nbsp;&nbsp;,&nbsp;tradePrice&nbsp;::&nbsp;Rational &nbsp;&nbsp;,&nbsp;tradeCurrency&nbsp;::&nbsp;String&nbsp;} &nbsp;&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#2b91af;">Eq</span>,&nbsp;<span style="color:#2b91af;">Show</span>)</pre> </p> <p> Shouldn't I introduce a <code>Money</code> type? I could, but I don't have to. As <a href="https://lexi-lambda.github.io">Alexis King</a> so clearly explains, <a href="https://lexi-lambda.github.io/blog/2020/01/19/no-dynamic-type-systems-are-not-inherently-more-open">you don't have to model more than you need to do the job</a>. </p> <p> By not introducing a <code>Money</code> type and making it an instance of various type classes, I still prevent client code from adding things together that shouldn't be added together. You can't add <code>Trade</code> values together because <code>Trade</code> isn't a <code>Num</code> instance. </p> <p> How do we calculate the notionals, then? It's easy; it's a one-liner: </p> <p> <pre><span style="color:#2b91af;">sumNotionals</span>&nbsp;::&nbsp;<span style="color:blue;">Foldable</span>&nbsp;t&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;t&nbsp;<span style="color:blue;">Trade</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Map</span>&nbsp;<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">Rational</span> sumNotionals&nbsp;=&nbsp;foldl&#39;&nbsp;(\m&nbsp;t&nbsp;-&gt;&nbsp;Map.insertWith&nbsp;<span style="color:#2b91af;">(+)</span>&nbsp;(key&nbsp;t)&nbsp;(value&nbsp;t)&nbsp;m)&nbsp;Map.empty &nbsp;&nbsp;<span style="color:blue;">where</span>&nbsp;key&nbsp;&nbsp;&nbsp;(Trade&nbsp;_&nbsp;_&nbsp;_&nbsp;currency)&nbsp;=&nbsp;currency &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;value&nbsp;(Trade&nbsp;quantity&nbsp;_&nbsp;price&nbsp;_)&nbsp;=&nbsp;<span style="color:blue;">toRational</span>&nbsp;quantity&nbsp;*&nbsp;price</pre> </p> <p> Okay, that looks more like four lines of code, but the first is an optional type declaration, so it doesn't count. The <code>key</code> and <code>value</code> functions could be inlined to make the function a single (wide) line of code, but I made them two named functions in order to make the code more readable. </p> <p> It gets the job done: </p> <p> <pre>*Trades&gt; sumNotionals trades fromList [("GBP",500 % 1),("JPY",250 % 1),("USD",900 % 1)]</pre> </p> <p> While this code addresses this particular problem, you probably consider it cheating because I've failed to address a wider concern. How does one model money in several currencies? I've <a href="/2017/10/16/money-monoid">previously covered that, including a simple Haskell example</a>, but in general, I consider it more productive to have a problem and <em>then</em> go looking for a solution, rather than inventing a solution and go looking for a problem. </p> <h3 id="8d472a61051e4ddfaf2698c8d215d658"> Summary <a href="#8d472a61051e4ddfaf2698c8d215d658" title="permalink">#</a> </h3> <p> When people enter into a debate, they use the knowledge they have. This is also the case in the debate about static versus dynamic types. Most programmers have experience with statically typed languages like C# or Java. It's natural to argue from what you know, and extrapolate from that. </p> <p> I think that when confronted with a phrase like <em>a more powerful type system</em>, many people extrapolate and think that they know what that means. They think that it means statically typed numbers on steroids. That's a red herring. </p> <p> That's usually not what we mean when we talk about <em>more powerful type systems</em>. We talk about algebraic data types, which make illegal states unrepresentable. Judged by the debates I've participated in, you can't <em>extrapolate</em> from mainstream type systems to algebraic data types. If you haven't tried programming with both sum and <a href="https://en.wikipedia.org/wiki/Product_type">product types</a>, you aren't going to <a href="http://bit.ly/stranger-in-a-strange-land">grok</a> what we mean when we talk about <em>strong type systems</em>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="61115b6622294923b7440cb1c4e32f84"> <div class="comment-author"><a href="https://github.com/Jankowski-J">Jakub Jankowski</a></div> <div class="comment-content"> <p> "but in general, I consider it more productive to have a problem and <em>then</em> go looking for a solution, rather than inventing a solution and go looking for a problem." </p> <p> This really resonates with me. I've been observing this in my current team and the tendency to "lookout" for the solutions to problems not yet present, just for the sake of "making it a robust solution" so to say. </p> <p> I really like the properties of the Haskell solution. It handles all the currencies (no matter how many of them come in the dataset) without explicitly specifying them. And you can't accidentally add two different currencies together. The last part would be pretty verbose to implement in C#. </p> </div> <div class="comment-date">2020-01-20 20:54 UTC</div> </div> <div class="comment" id="a496e710c3ea4391a9de433da3e6d54d"> <div class="comment-author"><a href="https://github.com/drewjcooper">Andrew Cooper</a></div> <div class="comment-content"> <p> I'm not sure the above is a good example of what you're trying to say about algebraic data types. The problem can be solve identically (at least semantically) in C#. Granted, the definition of the <code>Trade</code> type would be way more verbose, but once you have that, the <code>SumNotionals</code> method is basically the same as you code, albeit with different syntax: </p> <p> <pre>Dictionary&lt;string,&nbsp;int&gt;&nbsp;SumNotionals(IEnumerable&lt;Trade&gt;&nbsp;trades) { &nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;trades &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.GroupBy(t&nbsp;=&gt;&nbsp;t.Currency,&nbsp;t&nbsp;=&gt&nbsp;t.Price&nbsp;*&nbsp;t.Quantity) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.ToDictionary(g&nbsp;=&gt;&nbsp;g.Key,&nbsp;g&nbsp;=&gt&nbsp;g.Sum()); }</pre> </p> <p> Am I missing something? </p> </div> <div class="comment-date">2020-01-20 22:30 UTC</div> </div> <div class="comment" id="bd48b3267e014ccc9b377e983369ddca"> <div class="comment-author"><a href="https://github.com/Jankowski-J">Jakub Jankowski</a></div> <div class="comment-content"> <p> You are right Andrew. The LINQ query indeed has the same properites as the Haskell function. </p> <p> I'm not sure what I was thinking yesterday, but I think I subconsciously "wanted" C# to be less robust. </p> </div> <div class="comment-date">2020-01-21 18:04 UTC</div> </div> <div class="comment" id="c9069e6554934325a86a27921cff7ac3"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Andrew, thank you for writing. I didn't intend to say much about algebraic data types in this article. It wasn't the topic I had in mind. It can be difficult to communicate any but the simplest ideas, so it's possible that I didn't state my intention well enough. If so, the fault is mine. I've <a href="/2016/11/28/easy-domain-modelling-with-types">tried to demonstrate the power of algebraic data types before</a>, so I didn't want to repeat the effort, since my agenda was another. That's why I linked to that other article. </p> <p> The reason I discussed Alex Nixon's blog post was that it was the article that originally inspired me to write this article. I always try to include an example so that the reader gets to see the connection between the general concept and specifics. </p> <p> I could have discussed Alex' article solely on its merits of showcasing failed attempts to model a 'stronger number'. That would, however, have left the reader without a resolution. I found that a bad way to structure my text. Readers would be left with questions. <em>Okay Mark, that's all fine, but then how would you solve the problem?</em> </p> <p> So I decided to include a simple solution in an attempt to <a href="https://en.wikipedia.org/wiki/Gordian_Knot">cut the Gordian know</a>, so to speak. </p> </div> <div class="comment-date">2020-01-22 14:11 UTC</div> </div> <div class="comment" id="d20281f1114f44738c29f4298c52a728"> <div class="comment-author"><a href="https://github.com/drewjcooper">Andrew Cooper</a></div> <div class="comment-content"> <p> Mark, thanks for your response. It does indeed clear up my confusion. In my eagerness to learn more about algrebraic data types I read the second half of your post the wrong way. Thanks for clearing it up. </p> </div> <div class="comment-date">2020-01-22 21:30 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. On doing katas https://blog.ploeh.dk/2020/01/13/on-doing-katas 2020-01-13T06:23:00+00:00 Mark Seemann <div id="post"> <p> <em>Approach programming katas differently than martial arts katas.</em> </p> <p> Would you like to become a better programmer? Then practice. It's no different from becoming a better musician, a better sports(wo)man, a better cook, a better artist, etcetera. </p> <p> How do you practice programming? </p> <p> There's many ways. Doing <a href="https://en.wikipedia.org/wiki/Kata_(programming)">programming katas</a> is one way. </p> <h3 id="16e8612d24b14930a4d7cc02ebad6fd6"> Variation, not repetition <a href="#16e8612d24b14930a4d7cc02ebad6fd6" title="permalink">#</a> </h3> <p> When I talk to other programmers about katas, I often get the impression that people fail to extract value from the exercises. You can find catalogues of exercises on the internet, but there's a dearth of articles that discuss <em>how</em> to do katas. </p> <p> Part of the problem is, I think, that <a href="https://en.wikipedia.org/wiki/Kata">the term comes from martial arts practice</a>. In martial arts, one repeats the same movements over and over again in order to build up <a href="https://en.wikipedia.org/wiki/Muscle_memory">muscle memory</a>. Repetition produces improvements. </p> <p> Some people translate that concept literally. They try to do programming katas by doing the <em>same exercise</em> again and again, with no variation. After a few days or weeks, they stop because they can't see the point. </p> <p> That's no wonder. Neither can I. </p> <p> Programming and software design is mostly an intellectual (and perhaps artistic) endeavour. Unless you can't <a href="https://en.wikipedia.org/wiki/Touch_typing">touch type</a>, there's little need to build up muscle memory. You train your brain unlike you train your muscles. Repetition numbs the brain. Variation stimulates it. </p> <h3 id="5e0804109e5c40cb80f0c3c9274afb30"> Suggested variations <a href="#5e0804109e5c40cb80f0c3c9274afb30" title="permalink">#</a> </h3> <p> I find that doing a kata is a great opportunity to explore alternatives. A kata is usually a limited exercise, which means that you can do it multiple times and compare outcomes. </p> <p> You can find various kata catalogues on the internet. One of my favourites is the <a href="http://bit.ly/codekatas">Coding Dojo</a>. Among the katas there, I particularly like the <a href="http://codingdojo.org/kata/Tennis">Tennis kata</a>. I'll use that as an example to describe how I often approach a kata. </p> <p> The first time I encounter a kata I've never done before, I do it with as little fuss as possible. I use the programming language I'm most comfortable with, and don't attempt any stunts. I no longer remember when I first encountered the Tennis kata, but it's many years ago, and C# was my preferred language. I'd do the Tennis kata in C#, then, just to get acquainted with the problem. </p> <p> Most good katas contain small surprises. They may sound simpler than they actually turn out to be. On the other hand, they're typically not overwhelmingly difficult. It pays to overcome the surprise the kata may hold without getting bogged down by trying some feat. The Tennis kata, for example, sounds easy, but most people stumble on the rules associated with <em>deuce</em> and <em>advantage</em>. How to model the API? How do you implement the algorithm? </p> <p> Once you're comfortable with the essence of the exercise, introduce variations. Most of the variations I use take the form of some sort of constraint. <a href="https://www.dotnetrocks.com/?show=1542">Constraints liberate</a>. <a href="/2015/04/13/less-is-more-language-features">Less is more</a>. </p> <p> Here's a list of suggestions: <ul> <li><a href="/2019/10/21/a-red-green-refactor-checklist">Follow test-driven development</a> (TDD). That's my usual modus operandi, but if you don't normally practice TDD, a kata is a great opportunity.</li> <li>Use the (<em>Gollum style</em>) <a href="/2019/10/07/devils-advocate">Devil's Advocate</a> technique with TDD.</li> <li>Follow the <a href="https://blog.cleancoder.com/uncle-bob/2013/05/27/TheTransformationPriorityPremise.html">Transformation Priority Premise</a>.</li> <li>Do TDD without mocks.</li> <li>Do TDD with mocks.</li> <li>Use the <a href="http://www.natpryce.com/articles/000714.html">Test Data Builder design pattern</a>.</li> <li>Try <a href="/property-based-testing-intro">property-based testing</a>. I've <a href="/2016/02/10/types-properties-software">done that with the Tennis</a> kata multiple times.</li> <li>Put your mouse away.</li> <ins datetime="2020-02-20T08:38Z"><li>Hide the file tree in your editor or IDE. In Visual Studio, this is called the <em>Solution Explorer</em>, in Visual Studio Code it's just <em>Explorer</em>. Navigate the code by other means.</li></ins> <li>Use another editor or IDE.</li> <li>Use another programming language. A kata is a great way to practice a new language. When you're learning a new language, you're often fighting with unfamiliar syntax, which is the reason I recommend that you <em>first</em> do the kata in a language with which you're familiar.</li> <li>Use only immutable data structures. This is a good first step towards learning functional programming.</li> <li>Keep the <a href="https://en.wikipedia.org/wiki/Cyclomatic_complexity">cyclomatic complexity</a> of all methods at <em>1</em>. I <a href="/2011/05/16/TennisKatawithimmutabletypesandacyclomaticcomplexityof1">once did that with the Tennis kata</a>.</li> <li>Use an unfamiliar API. If you normally use <a href="https://nunit.org">NUnit</a> then try <a href="https://xunit.net">xUnit.net</a> instead. Use a new Test Double library. Use a different assertion library. I once did the Tennis kata in <a href="https://www.haskell.org">Haskell</a> using the <a href="http://hackage.haskell.org/package/lens">lens</a> library because I wanted to hone those skills. I've also done the <em>Mark IV coffee maker</em> exercise from <a href="http://amzn.to/19W4JHk">APPP</a> with <a href="http://reactivex.io">Reactive Extensions</a>.</li> <li>Employ a design pattern you'd like to understand better. I've had particular success with the <a href="https://en.wikipedia.org/wiki/Visitor_pattern">Visitor design pattern</a>.</li> <li>Refactor an existing kata solution to another design.</li> <li>Refactor another programmer's kata solution.</li> <li><a href="https://en.wikipedia.org/wiki/Pair_programming">Pair-program</a> the kata.</li> <li>Use the <a href="http://wiki.c2.com/?PairProgrammingPingPongPattern">Ping Pong pattern</a> when pair programming.</li> <li><a href="https://en.wikipedia.org/wiki/Mob_programming">Mob-program</a> it.</li> </ul> You'll probably come up with your own list of variations. </p> <p> What I like about katas is that they're small enough that you can do the same exercise multiple times, but with different designs. This makes it easy to learn new ways of doing things, because you can compare different approaches to the same problem. </p> <h3 id="1faffc34ac644021b87c7f0b0691eeef"> Conclusion <a href="#1faffc34ac644021b87c7f0b0691eeef" title="permalink">#</a> </h3> <p> The way that the idea of a programming kata <a href="http://www.butunclebob.com/ArticleS.UncleBob.TheProgrammingDojo">was originally introduced</a> is a bit unfortunate. On one hand, the metaphor may have helped adoption because martial arts are cool, and Japanese is a beautiful language. On the other hand, the underlying message is one of repetition, which is hardly helpful when it comes to exercising the brain. </p> <p> Repetition dulls the brain, while variation stimulates it. Katas are great because they're short exercises, but you have to deliberately introduce diversity to make them work for you. You're not building muscle memory, you're forming new neural pathways. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="?"> <div class="comment-author">Johannes Schmitt</div> <div class="comment-content"> <p> Regarding kata variations, I'd like mention Jeff Bay's <i>Object Calisthenics</i> (by Jeff Bay). One could use all rules at once or just a subset of them. </p> <p> Just briefly, this are the rules (details can be found on the web): <ul> <li>One level of indentation per method</li> <li>Don’t use the ELSE keyword</li> <li>Wrap all primitives and strings</li> <li>First class collections</li> <li>One dot per line</li> <li>Don't abbreviate</li> <li>Keep all entities small</li> <li>No classes with more than two instance variables</li> <li>No getters/setters/properties</li> </ul> </p> </div> <div class="comment-date">2020-01-14 12:42 UTC</div> </div> <div class="comment" id="cd5aa5d8944e48c59937986d9fbe464e"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Johannes, that list is a great addition to my suggestions. Thank you. </p> </div> <div class="comment-date">2020-01-14 13:58 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. The case of the unbalanced brackets https://blog.ploeh.dk/2020/01/06/the-case-of-the-unbalanced-brackets 2020-01-06T06:37:00+00:00 Mark Seemann <div id="post"> <p> <em>A code mystery.</em> </p> <p> One of my clients was kind enough to let me look at some of their legacy code. As I was struggling to understand how it worked, I encountered something that <em>looked</em> like this: </p> <p> <pre>ApplyDueAmountG89.<span style="font-weight:bold;color:#74531f;">Calculate</span>(<span style="font-weight:bold;color:#1f377f;">postState</span>.PartialMebershipsBAT.<span style="font-weight:bold;color:#74531f;">Where</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">d</span>&nbsp;=&gt;&nbsp;(<span style="font-weight:bold;color:#1f377f;">d</span>.Data.Choicetype&nbsp;==&nbsp;<span style="color:#2b91af;">GarplyChoicetype</span>.AtoC&nbsp;|| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">retirablePartialMembershipNr</span>.<span style="font-weight:bold;color:#74531f;">Contains</span>(<span style="font-weight:bold;color:#1f377f;">d</span>.Data.PartialMembershipNr)).<span style="font-weight:bold;color:#74531f;">ToList</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ApplyDueAmountG89.Situation.Depreciation, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ApplyDueAmountG89.RecordType.Primo);</pre> </p> <p> For the record, this isn't the actual code that my client gave me. I wouldn't post someone else's code without their permission. It is, however, a faithful imitation of the original code. What's wrong with it? </p> <p> I'll wait. </p> <h3 id="4eb9d6fa6cf04f45a4afdeb3638a9c8a"> Brackets <a href="#4eb9d6fa6cf04f45a4afdeb3638a9c8a" title="permalink">#</a> </h3> <p> Count the brackets. There's a missing closing bracket. </p> <p> Yet, the code compiles. How? </p> <p> Legacy code isn't <a href="https://cleancoders.com/video-details/humane-code-real-episode-1">humane code</a>. There's a multitude of ways in which code can be obscure. This article describes one of them. </p> <p> When brackets are nested and far apart, it's hard for the brain to parse and balance them. Yet, on closer inspection the brackets seem unbalanced. </p> <h3 id="0595d741e4ff4a139d3b26ab8fb3e75d"> Show whitespace <a href="#0595d741e4ff4a139d3b26ab8fb3e75d" title="permalink">#</a> </h3> <p> Ever since I started programming in <a href="https://fsharp.org">F#</a>, I've turned on the Visual Studio feature that shows whitespace. F# does, after all, use <a href="/2020/05/04/significant-whitespace-is-dry">significant whitespace</a> (AKA the <a href="https://en.wikipedia.org/wiki/Off-side_rule">Off-side rule</a>), and it helps to be able to detect if a tab character has slipped in among the spaces. </p> <p> Visual Studio shows whitespace with pale blue dots and arrows. When that feature is turned on (<kbd>Ctrl</kbd> + <kbd>e</kbd>, <kbd>s</kbd>), the above code example looks different: </p> <p> <pre>ApplyDueAmountG89.<span style="font-weight:bold;color:#74531f;">Calculate</span>(<span style="font-weight:bold;color:#1f377f;">postState</span>.PartialMebershipsBAT.<span style="font-weight:bold;color:#74531f;">Where</span>( <span style="color:#2b91af;">&middot;&middot;&middot;&middot;</span><span style="font-weight:bold;color:#1f377f;">d</span><span style="color:#2b91af;">&middot;</span>=&gt;<span style="color:#2b91af;">&middot;</span>(<span style="font-weight:bold;color:#1f377f;">d</span>.Data.Choicetype<span style="color:#2b91af;">&middot;</span>==<span style="color:#2b91af;">&middot;</span><span style="color:#2b91af;">GarplyChoicetype</span>.AtoC<span style="color:#2b91af;">&middot;</span>||<span style="color:#2b91af;">&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;</span> <span style="color:#2b91af;">&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;</span><span style="font-weight:bold;color:#1f377f;">retirablePartialMembershipNr</span>.<span style="font-weight:bold;color:#74531f;">Contains</span>(<span style="font-weight:bold;color:#1f377f;">d</span>.Data.PartialMembershipNr)).<span style="font-weight:bold;color:#74531f;">ToList</span>(), <span style="color:#2b91af;">&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;</span>ApplyDueAmountG89.Situation.Depreciation, <span style="color:#2b91af;">&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;&middot;</span>ApplyDueAmountG89.RecordType.Primo);</pre> </p> <p> Notice the space characters that seem to run off to the right of the <code>||</code> operator. What's at the end of those spaces? </p> <p> Yes, you guessed it: another Boolean expression, including the missing closing bracket: </p> <p> <pre><span style="font-weight:bold;color:#1f377f;">d</span>.Data.Choicetype&nbsp;==&nbsp;<span style="color:#2b91af;">GarplyChoicetype</span>.BtoC)&nbsp;&amp;&amp;</pre> </p> <p> If you delete all those redundant spaces, this is the actual code: </p> <p> <pre>ApplyDueAmountG89.<span style="font-weight:bold;color:#74531f;">Calculate</span>(<span style="font-weight:bold;color:#1f377f;">postState</span>.PartialMebershipsBAT.<span style="font-weight:bold;color:#74531f;">Where</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">d</span>&nbsp;=&gt;&nbsp;(<span style="font-weight:bold;color:#1f377f;">d</span>.Data.Choicetype&nbsp;==&nbsp;<span style="color:#2b91af;">GarplyChoicetype</span>.AtoC&nbsp;||&nbsp;<span style="font-weight:bold;color:#1f377f;">d</span>.Data.Choicetype&nbsp;==&nbsp;<span style="color:#2b91af;">GarplyChoicetype</span>.BtoC)&nbsp;&amp;&amp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">retirablePartialMembershipNr</span>.<span style="font-weight:bold;color:#74531f;">Contains</span>(<span style="font-weight:bold;color:#1f377f;">d</span>.Data.PartialMembershipNr)).<span style="font-weight:bold;color:#74531f;">ToList</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ApplyDueAmountG89.Situation.Depreciation, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ApplyDueAmountG89.RecordType.Primo);</pre> </p> <p> Imagine troubleshooting code like that, and not realising that there's another Boolean expression so far right that even a large screen doesn't show it. In the actual legacy code where I found this example, the extra Boolean expression started at column 209. </p> <h3 id="8a3d025a78304704864a782aa162e6e3"> Conclusion <a href="#8a3d025a78304704864a782aa162e6e3" title="permalink">#</a> </h3> <p> Hiding significant code so far right that it's effectively invisible seems positively <em>evil</em>, but I don't think anyone did it deliberately. Rather, my guess is that someone performed a search-and-replace through the code base, and that this automatic change somehow removed a newline character. </p> <p> In any case, keeping an eye on the line width of code could prevent something like this from happening. <a href="/2019/11/04/the-80-24-rule">Stay within 80 characters</a>. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Semigroup resonance FizzBuzz https://blog.ploeh.dk/2019/12/30/semigroup-resonance-fizzbuzz 2019-12-30T10:44:00+00:00 Mark Seemann <div id="post"> <p> <em>An alternative solution to the FizzBuzz kata.</em> </p> <p> A common solution to the <a href="http://codingdojo.org/kata/FizzBuzz/">FizzBuzz kata</a> is to write a loop from 1 to 100 and perform a modulo check for each number. Functional programming languages like <a href="https://www.haskell.org">Haskell</a> don't have loops, so instead you'd typically solve the kata like this: </p> <p> <pre><span style="color:#2b91af;">isAMultipleOf</span>&nbsp;::&nbsp;<span style="color:blue;">Integral</span>&nbsp;a&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">Bool</span> isAMultipleOf&nbsp;i&nbsp;multiplier&nbsp;=&nbsp;i&nbsp;`mod`&nbsp;multiplier&nbsp;==&nbsp;0 <span style="color:#2b91af;">convert</span>&nbsp;::&nbsp;(<span style="color:blue;">Integral</span>&nbsp;a,&nbsp;<span style="color:blue;">Show</span>&nbsp;a)&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">String</span> convert&nbsp;i&nbsp;|&nbsp;i&nbsp;`isAMultipleOf`&nbsp;3&nbsp;&amp;&amp;&nbsp;i&nbsp;`isAMultipleOf`&nbsp;5&nbsp;=&nbsp;<span style="color:#a31515;">&quot;FizzBuzz&quot;</span> convert&nbsp;i&nbsp;|&nbsp;i&nbsp;`isAMultipleOf`&nbsp;3&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Fizz&quot;</span> convert&nbsp;i&nbsp;|&nbsp;i&nbsp;`isAMultipleOf`&nbsp;5&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Buzz&quot;</span> convert&nbsp;i&nbsp;=&nbsp;<span style="color:blue;">show</span>&nbsp;i <span style="color:#2b91af;">main</span>&nbsp;::&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;() main&nbsp;=&nbsp;<span style="color:blue;">mapM_</span>&nbsp;<span style="color:blue;">putStrLn</span>&nbsp;$&nbsp;convert&nbsp;&lt;$&gt;&nbsp;[1..100]</pre> </p> <p> There's more than one way to skin this cat. In this article, I'll demonstrate one based on <code>Semigroup</code> resonance. </p> <h3 id="66370c86e5c74b44a18bb9827c7dc34e"> Fizz stream <a href="#66370c86e5c74b44a18bb9827c7dc34e" title="permalink">#</a> </h3> <p> The fundamental idea is to use infinite streams that repeat at different intervals. That idea isn't mine, but I've never seen it done without resorting to some sort of Boolean conditional or pattern matching. </p> <p> You start with a finite sequence of values that represent the pulse of <em>Fizz</em> values: </p> <p> <pre>[Nothing,&nbsp;Nothing,&nbsp;Just&nbsp;<span style="color:#a31515;">&quot;Fizz&quot;</span>]</pre> </p> <p> If you repeat that sequence indefinitely, you now have a pulse of <em>Fizz</em> values: </p> <p> <pre><span style="color:#2b91af;">fizzes</span>&nbsp;::&nbsp;[<span style="color:#2b91af;">Maybe</span>&nbsp;<span style="color:#2b91af;">String</span>] fizzes&nbsp;=&nbsp;<span style="color:blue;">cycle</span>&nbsp;[Nothing,&nbsp;Nothing,&nbsp;Just&nbsp;<span style="color:#a31515;">&quot;Fizz&quot;</span>]</pre> </p> <p> This stream of values is one-based, since the first two entries are <code>Nothing</code>, and only every third is <code>Just "Fizz"</code>: </p> <p> <pre>*FizzBuzz&gt; take 9 fizzes [Nothing, Nothing, Just "Fizz", Nothing, Nothing, Just "Fizz", Nothing, Nothing, Just "Fizz"]</pre> </p> <p> If you're wondering why I chose a stream of <code>Maybe String</code> instead of just a stream of <code>String</code> values, I'll explain that now. </p> <h3 id="000531d5739e4d3bbaeff702e052ca6c"> Buzz stream <a href="#000531d5739e4d3bbaeff702e052ca6c" title="permalink">#</a> </h3> <p> You can define an equivalent infinite stream of <em>Buzz</em> values: </p> <p> <pre><span style="color:#2b91af;">buzzes</span>&nbsp;::&nbsp;[<span style="color:#2b91af;">Maybe</span>&nbsp;<span style="color:#2b91af;">String</span>] buzzes&nbsp;=&nbsp;<span style="color:blue;">cycle</span>&nbsp;[Nothing,&nbsp;Nothing,&nbsp;Nothing,&nbsp;Nothing,&nbsp;Just&nbsp;<span style="color:#a31515;">&quot;Buzz&quot;</span>]</pre> </p> <p> The idea is the same, but the rhythm is different: </p> <p> <pre>*FizzBuzz&gt; take 10 buzzes [Nothing, Nothing, Nothing, Nothing, Just "Buzz", Nothing, Nothing, Nothing, Nothing, Just "Buzz"]</pre> </p> <p> Why not simply generate a stream of <code>String</code> values, like the following? </p> <p> <pre>*FizzBuzz&gt; take 10 $ cycle ["", "", "", "", "Buzz"] ["", "", "", "", "Buzz", "", "", "", "", "Buzz"]</pre> </p> <p> At first glance this looks simpler, but it makes it harder to merge the stream of <em>Fizz</em> and <em>Buzz</em> values with actual numbers. Distinguishing between <code>Just</code> and <code>Nothing</code> values enables you to use the <em>Maybe catamorphism</em>. </p> <h3 id="f95fb4415768473ca8fdc576e227882c"> Resonance <a href="#f95fb4415768473ca8fdc576e227882c" title="permalink">#</a> </h3> <p> You can now <em>zip</em> the <code>fizzes</code> with the <code>buzzes</code>: </p> <p> <pre><span style="color:#2b91af;">fizzBuzzes</span>&nbsp;::&nbsp;[<span style="color:#2b91af;">Maybe</span>&nbsp;<span style="color:#2b91af;">String</span>] fizzBuzzes&nbsp;=&nbsp;<span style="color:blue;">zipWith</span>&nbsp;<span style="color:#2b91af;">(&lt;&gt;)</span>&nbsp;fizzes&nbsp;buzzes</pre> </p> <p> You combine the values by monoidal composition. Any <code>Maybe</code> over a <code>Semigroup</code> itself gives rise to a <code>Monoid</code>, and since <code>String</code> forms a <code>Monoid</code> (and therefore also a <code>Semigroup</code>) over concatenation, you can <em>zip</em> the two streams using the <code>&lt;&gt;</code> operator. </p> <p> <pre>*FizzBuzz&gt; take 20 fizzBuzzes [Nothing, Nothing, Just "Fizz", Nothing, Just "Buzz", Just "Fizz", Nothing, Nothing, Just "Fizz", Just "Buzz", Nothing, Just "Fizz", Nothing, Nothing, Just "FizzBuzz", Nothing, Nothing, Just "Fizz", Nothing, Just "Buzz"]</pre> </p> <p> Notice how the stream of <code>fizzes</code> enters into a resonance pattern with the stream of <code>buzzes</code>. Every fifteenth element the values <em>Fizz</em> and <em>Buzz</em> amplify each other and become <em>FizzBuzz</em>. </p> <h3 id="ef186fa307bd47b8a1651761cc1ae7af"> Numbers <a href="#ef186fa307bd47b8a1651761cc1ae7af" title="permalink">#</a> </h3> <p> While you have an infinite stream of <code>fizzBuzzes</code>, you also need a list of numbers. That's easy: </p> <p> <pre><span style="color:#2b91af;">numbers</span>&nbsp;::&nbsp;[<span style="color:#2b91af;">String</span>] numbers&nbsp;=&nbsp;<span style="color:blue;">show</span>&nbsp;&lt;$&gt;&nbsp;[1..100]</pre> </p> <p> You just use a list comprehension and map each number to its <code>String</code> representation using <code>show</code>: </p> <p> <pre>*FizzBuzz&gt; take 18 numbers ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18"]</pre> </p> <p> Now you just need to figure out how to merge the <code>fizzBuzzes</code> with the <code>numbers</code>. </p> <h3 id="a84444b7decc42f1b2fb22b7a02718aa"> Zip with catamorphism <a href="#a84444b7decc42f1b2fb22b7a02718aa" title="permalink">#</a> </h3> <p> While you can trivially <code>zip</code> <code>fizzBuzzes</code> with <code>numbers</code>, it doesn't solve the problem of which value to pick: </p> <p> <pre>*FizzBuzz&gt; take 5 $ zip numbers fizzBuzzes [("1", Nothing), ("2", Nothing), ("3", Just "Fizz"), ("4", Nothing), ("5", Just "Buzz")]</pre> </p> <p> You want to use the second element of each tuple when there's a value, and only use the first element (the number) when the second element is <code>Nothing</code>. </p> <p> That's easily done with <code>fromMaybe</code> (you'll need to <code>import Data.Maybe</code> for that): </p> <p> <pre>*FizzBuzz&gt; fromMaybe "2" Nothing "2" *FizzBuzz&gt; fromMaybe "3" $ Just "Fizz" "Fizz"</pre> </p> <p> That's just what you need, so <em>zip</em> <code>numbers</code> with <code>fizzBuzzes</code> using <code>fromMaybe</code>: </p> <p> <pre><span style="color:#2b91af;">elements</span>&nbsp;::&nbsp;[<span style="color:#2b91af;">String</span>] elements&nbsp;=&nbsp;<span style="color:blue;">zipWith</span>&nbsp;fromMaybe&nbsp;numbers&nbsp;fizzBuzzes</pre> </p> <p> These <code>elements</code> is a list of the values the kata instructs you to produce: </p> <p> <pre>*FizzBuzz&gt; take 14 elements ["1", "2", "Fizz", "4", "Buzz", "Fizz", "7", "8", "Fizz", "Buzz", "11", "Fizz", "13", "14"]</pre> </p> <p> <code>fromMaybe</code> is a specialisation of the <a href="/2019/05/20/maybe-catamorphism">Maybe catamorphism</a>. I always find it interesting when I can solve a problem with <a href="/2019/04/29/catamorphisms">catamorphisms</a> and <a href="/2017/10/06/monoids">monoids</a>, because it shows that perhaps, there's some value in knowing <a href="/2017/10/04/from-design-patterns-to-category-theory">universal abstractions</a>. </p> <h3 id="02f08a325df6462994e6081928bf67bc"> From 1 to 100 <a href="#02f08a325df6462994e6081928bf67bc" title="permalink">#</a> </h3> <p> The kata instructions are to write a program that prints the numbers from 1 to 100, according to the special rules. You can use <code>mapM_ putStrLn</code> for that: </p> <p> <pre><span style="color:#2b91af;">main</span>&nbsp;::&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;() main&nbsp;=&nbsp;<span style="color:blue;">mapM_</span>&nbsp;<span style="color:blue;">putStrLn</span>&nbsp;elements</pre> </p> <p> When you execute the <code>main</code> function, you get the desired output: </p> <p> <pre>1 2 Fizz 4 Buzz Fizz 7 8 Fizz Buzz 11 Fizz 13 14 FizzBuzz 16</pre> </p> <p> ... and so on. </p> <h3 id="399d6c6550344aa29b5bb2a88ff8c216"> Golf <a href="#399d6c6550344aa29b5bb2a88ff8c216" title="permalink">#</a> </h3> <p> Haskell <a href="https://en.wikipedia.org/wiki/Code_golf">golfers</a> may complain that the above code is unnecessarily verbose. I disagree, but you can definitely write the entire kata as a 'one-liner' if you want to: </p> <p> <pre><span style="color:#2b91af;">main</span>&nbsp;::&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;() main&nbsp;= &nbsp;&nbsp;<span style="color:blue;">mapM_</span>&nbsp;<span style="color:blue;">putStrLn</span>&nbsp;$ &nbsp;&nbsp;<span style="color:blue;">zipWith</span>&nbsp;fromMaybe&nbsp;(<span style="color:blue;">show</span>&nbsp;&lt;$&gt;&nbsp;[1..100])&nbsp;$ &nbsp;&nbsp;<span style="color:blue;">zipWith</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">(&lt;&gt;)</span> &nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:blue;">cycle</span>&nbsp;[Nothing,&nbsp;Nothing,&nbsp;Just&nbsp;<span style="color:#a31515;">&quot;Fizz&quot;</span>]) &nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:blue;">cycle</span>&nbsp;[Nothing,&nbsp;Nothing,&nbsp;Nothing,&nbsp;Nothing,&nbsp;Just&nbsp;<span style="color:#a31515;">&quot;Buzz&quot;</span>])</pre> </p> <p> I've just mechanically in-lined all the values like <code>fizzes</code>, <code>buzzes</code>, etc. and formatted the code so that it fits comfortable in a <a href="/2019/11/04/the-80-24-rule">80x24 box</a>. Apart from that, I don't think that this is an improvement, but it has the same behaviour as the above, more verbose alternative. </p> <h3 id="1325c76bbf924cb58db4e7782bb95cfd"> Conclusion <a href="#1325c76bbf924cb58db4e7782bb95cfd" title="permalink">#</a> </h3> <p> You can implement the FizzBuzz kata using the fundamental concepts <em>catamorphism</em>, <em>semigroup</em> and <em>monoid</em>. No <code>if-then-else</code> instructions or pattern matching is required. Instead, you use the string concatenation semigroup to enable resonance between two pulses, and the <em>maybe catamorphism</em> to combine with the list of numbers. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. The case of the mysterious curly bracket https://blog.ploeh.dk/2019/12/23/the-case-of-the-mysterious-curly-bracket 2019-12-23T06:46:00+00:00 Mark Seemann <div id="post"> <p> <em>The story of a curly bracket that I thought was redundant. Not so.</em> </p> <p> One of my clients was kind enough to show me some of their legacy code. As I was struggling to understand how it worked, I encountered something like this: </p> <p> <pre><span style="color:green;">//&nbsp;A&nbsp;lot&nbsp;of&nbsp;code&nbsp;has&nbsp;come&nbsp;before&nbsp;this.&nbsp;This&nbsp;is&nbsp;really&nbsp;on&nbsp;line&nbsp;665,&nbsp;column&nbsp;29.</span> <span style="font-weight:bold;color:#8f08c4;">foreach</span>&nbsp;(<span style="color:#2b91af;">BARLifeScheme_BAR</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">scheme</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">in</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">postPartialMembership</span>.<span style="font-weight:bold;color:#74531f;">SchemesFilterObsolete</span>(<span style="color:#2b91af;">BARCompany</span>.ONETIMESUM,&nbsp;<span style="color:blue;">false</span>)) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">schemeCalculated</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:#2b91af;">BARLifeSchemeCalculated_BAR</span>)<span style="font-weight:bold;color:#1f377f;">scheme</span>.SchemeCalculatedObsolete[<span style="font-weight:bold;color:#1f377f;">basis</span>.Data.Basis1order]; &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">decimal</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">hfcFactor</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">postState</span>.OverallFuturerule&nbsp;==&nbsp;<span style="color:#2b91af;">BAROverallFuturerule</span>.Standard) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">bonusKey</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">BonusKey</span>(<span style="font-weight:bold;color:#1f377f;">postState</span>.<span style="font-weight:bold;color:#74531f;">PNr</span>()); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">hfcFactor</span>&nbsp;=&nbsp;1M&nbsp;-&nbsp;<span style="color:#2b91af;">CostFactory</span>.<span style="color:#74531f;">Instance</span>() &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">CostProvider</span>(<span style="font-weight:bold;color:#1f377f;">postState</span>.Data.FrameContractNr,&nbsp;<span style="font-weight:bold;color:#1f377f;">postState</span>.StateDate) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">GetAdministrationpercentageContribution</span>(<span style="font-weight:bold;color:#1f377f;">bonusKey</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">basis</span>.Data.Basis1order) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/&nbsp;100M; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;Much&nbsp;more&nbsp;code&nbsp;comes&nbsp;after&nbsp;this...</span> &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;...and&nbsp;after&nbsp;this...</span> }</pre> </p> <p> For the record, this isn't the actual code that my client gave me. I wouldn't post someone else's code without their permission. It is, however, a faithful imitation of the original code. </p> <p> The actual code started at line 665 and further to the right. It was part of a larger block of code with <code>if</code> statements within <code>foreach</code> loops within <code>if</code> statements within <code>foreach</code> loops, and so on. The <code>foreach</code> keyword actually appeared at column 29. The entire file was 1708 lines long. </p> <p> The code has numerous smells, but here I'll focus on a single oddity. </p> <h3 id="62fa371342be48698054d125b8b326e0"> Inexplicable bracket <a href="#62fa371342be48698054d125b8b326e0" title="permalink">#</a> </h3> <p> Notice the curly bracket on the line before <code>hfcFactor</code>. Why is it there? </p> <p> Take a moment and see if you can guess. </p> <p> It doesn't seem to be required. It just surrounds a block of code, but it belongs to none of the usual language constructs that would normally call for the use of curly brackets. There's no <code>if</code>, <code>foreach</code>, <code>using</code>, or <code>try</code> before it. </p> <h3 id="f56822a0b88d4d288843723fece26f76"> Residue <a href="#f56822a0b88d4d288843723fece26f76" title="permalink">#</a> </h3> <p> I formed a theory as to why those brackets where in place. I thought that it might be the residue of an <code>if</code> statement that was no longer there; that, perhaps, once the code had looked like this: </p> <p> <pre><span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">something</span>&nbsp;&lt;&nbsp;<span style="font-weight:bold;color:#1f377f;">somethingElse</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">decimal</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">hfcFactor</span>;</pre> </p> <p> Later, a developer had discovered that the code in that block should <em>always</em> be executed, and had removed the <code>if</code> statement without removing the curly brackets. </p> <p> That was my theory, but then I noticed that this structure appeared frequently throughout the code. Mysterious curly brackets were common, sometimes even nesting each other. </p> <p> This idiom appeared too often that it looked like the legacy from earlier epochs. It looked deliberate. </p> <h3 id="1b30ee97ed92442caf8d054b4239e334"> The real reason <a href="#1b30ee97ed92442caf8d054b4239e334" title="permalink">#</a> </h3> <p> When I had the opportunity, I asked one of the developers. </p> <p> He smiled sheepishly when he told me that those curly brackets were there to introduce a <em>variable scope</em>. The curly brackets protected variables within them from colliding with other variables elsewhere in the 744-line method. </p> <p> Those scopes enabled programmers to declare variables with names that would otherwise collide with other variables. They even enabled developers to declare a variable with the same name, but a different type. </p> <p> I was appalled. </p> <h3 id="c0fc550039c341ac81340d20d4011e29"> Legacy <a href="#c0fc550039c341ac81340d20d4011e29" title="permalink">#</a> </h3> <p> I didn't write this article to point fingers. I don't think that professional software developers deliberately decide to write obscure code. </p> <p> Code becomes obscure over time. It's a slow, unyielding process. As Brian Foote and Joseph Yoder wrote in <em>The Selfish Class</em> (here quoted from <a href="http://amzn.to/1dEKjcj">Pattern Languages of Program Design 3</a>, p. 461): <blockquote> <p>"Will highly comprehensible code, by virtue of being easy to modify, inevitably be supplanted by increasingly less elegant code until some equilibrium is achieved between comprehensibility and fragility?"</p> <footer><cite>Brian Foote and Joseph Yoder</cite></footer> </blockquote> That's a disturbing thought. It suggests that 'good' code is unstable. I suspect that code tends to rot beyond comprehension. It's death by a thousand cuts. It's not any single edit that produces legacy code. It's the glacial, inexorable slide towards increasingly complicated code. </p> <h3 id="76d3bcfd084247ed8eb9c11239c7523c"> Conclusion <a href="#76d3bcfd084247ed8eb9c11239c7523c" title="permalink">#</a> </h3> <p> Methods may grow to such sizes that variables collide. The solution isn't to add artificial variable scopes. The solution is to extract helper methods. <a href="/2019/11/04/the-80-24-rule">Keep methods small</a>. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Zone of Ceremony https://blog.ploeh.dk/2019/12/16/zone-of-ceremony 2019-12-16T09:51:00+00:00 Mark Seemann <div id="post"> <p> <em>Static typing doesn't have to involve much ceremony.</em> </p> <p> I seem to get involved in long and passionate debates about static versus dynamic typing on a regular basis. I find myself clearly on the side of static typing, but this article isn't about the virtues of static versus dynamic typing. The purpose is to correct a common misconception about statically typed languages. </p> <h3 id="07df6b539dd24732bd2c1f0038a27a71"> Ceremony <a href="#07df6b539dd24732bd2c1f0038a27a71" title="permalink">#</a> </h3> <p> People who favour dynamically typed languages over statically typed languages often emphasise that they find the lack of ceremony productive. That seems reasonable; only, it's a false dichotomy. </p> <ins datetime="2019-12-18T11:27Z"> <blockquote> <p> "Ceremony is what you have to do before you get to do what you really want to do." </p> <footer><cite><a href="https://youtu.be/4jCjDEb9KZI">Venkat Subramaniam</a></cite></footer> </blockquote> </ins> <p> Dynamically typed languages do seem to be light on ceremony, but you can't infer from that that statically typed languages have to require lots of ceremony. Unfortunately, all mainstream statically typed languages belong to the same family, and they <em>do</em> involve ceremony. I think that people extrapolate from what they know; they falsely conclude that all statically typed languages must come with the overhead of ceremony. </p> <p> It looks to me more as though there's an unfortunate <em>Zone of Ceremony</em>: </p> <p> <img src="/content/binary/zone-of-ceremony.png" alt="A conceptual spectrum of typing, from dynamic on the left, to static on the right. There's a zone of ceremony slightly to the right of the middle with the languages C++, C#, and Java."> </p> <p> Such a diagram can never be anything but a simplification, but I hope that it's illuminating. C++, Java, and C# are all languages that involve ceremony. To the right of them are what we could term the <em>trans-ceremonial languages</em>. These include <a href="https://fsharp.org">F#</a> and <a href="https://www.haskell.org">Haskell</a>. </p> <ins datetime="2019-12-18T19:30Z"> <p> In the following, I'll show some code examples in various languages. I'll discuss ceremony according to the above definition. The discussion focuses on the amount of preparatory work one has to do, such as creating a new file, declaring a new class, and declaring types. The discussion is <em>not</em> about the implementation code. For that reason, I've removed colouring from the implementation code, and emphasised the code that I consider ceremonial. </p> </ins> <h3 id="32ff9013011b4c04a24e32d635b55ab2"> Low ceremony of JavaScript <a href="#32ff9013011b4c04a24e32d635b55ab2" title="permalink">#</a> </h3> <p> Imagine that you're given a list of numbers, as well as a quantity. The quantity is a number to be consumed. You must remove elements from the left until you've consumed at least that quantity. Then return the rest of the list. </p> <p> <pre>&gt; consume ([1,2,3], 1); [ 2, 3 ] &gt; consume ([1,2,3], 2); [ 3 ] &gt; consume ([1,2,3], 3); [ 3 ] &gt; consume ([1,2,3], 4); []</pre> </p> <p> The first example consumes only the leading <code>1</code>, while both the second and the third example consumes both <code>1</code> and <code>2</code> because the sum of those values is <code>3</code>, and the requested quantity is <code>2</code> and <code>3</code>, respectively. The fourth example consumes all elements because the requested quantity is <code>4</code>, and you need both <code>1</code>, <code>2</code>, and <code>3</code> before the sum is large enough. You have to pick strictly from the left, so you can't decide to just take the elements <code>1</code> and <code>3</code>. </p> <ins datetime="2020-04-27T14:40Z"> <p> If you're wondering why such a function would be useful, <a href="/2020/04/27/an-f-implementation-of-the-maitre-d-kata">here's my motivating example</a>. </p> </ins> <p> In JavaScript, you could implement the <code>consume</code> function like this: </p> <p> <pre><strong><span style="color:blue;">var</span>&nbsp;consume&nbsp;=&nbsp;<span style="color:blue;">function</span>&nbsp;(source,&nbsp;quantity)&nbsp;{</strong> <span style="color: silver;">&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(!source)&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;[]; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;var&nbsp;accumulator&nbsp;=&nbsp;0; &nbsp;&nbsp;&nbsp;&nbsp;var&nbsp;result&nbsp;=&nbsp;[]; &nbsp;&nbsp;&nbsp;&nbsp;for&nbsp;(var&nbsp;i&nbsp;=&nbsp;0;&nbsp;i&nbsp;&lt;&nbsp;source.length;&nbsp;i++)&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;var&nbsp;x&nbsp;=&nbsp;source[i]; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(quantity&nbsp;&lt;=&nbsp;accumulator) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;result.push(x); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;accumulator&nbsp;+=&nbsp;x; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;result;</span> <strong>}</strong></pre> </p> <p> I'm a terrible JavaScript programmer, so I'm sure that it could have been done more elegantly, but as far as I can tell, it gets the job done. I wrote some tests, and I have 17 passing test cases. The point isn't about how you write the function, but how much ceremony is required. In JavaScript you don't need to declare any types. Just name the function and its arguments, and you're ready to write code. </p> <h3 id="2b1bcebf36084abcae5bb231ca0ebe15"> High ceremony of C# <a href="#2b1bcebf36084abcae5bb231ca0ebe15" title="permalink">#</a> </h3> <p> Contrast the JavaScript example with C#. The same function in C# would look like this: </p> <p> <pre><strong><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">Enumerable</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:blue;">int</span>&gt;&nbsp;<span style="color:#74531f;">Consume</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:blue;">int</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">source</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">quantity</span>) &nbsp;&nbsp;&nbsp;&nbsp;{</strong> <span style="color: silver;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(source&nbsp;is&nbsp;null) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;yield&nbsp;break; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;var&nbsp;accumulator&nbsp;=&nbsp;0; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;foreach&nbsp;(var&nbsp;i&nbsp;in&nbsp;source) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(quantity&nbsp;&lt;=&nbsp;accumulator) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;yield&nbsp;return&nbsp;i; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;accumulator&nbsp;+=&nbsp;i; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}</span> <strong>&nbsp;&nbsp;&nbsp;&nbsp;} }</strong></pre> </p> <p> Here you have to declare the type of each method argument, as well as the return type of the method. You also have to put the method in a class. This may not seem like much overhead, but if you later need to change the types, editing is required. This can affect downstream callers, so simple type changes ripple through code bases. </p> <p> It gets worse, though. The above <code>Consume</code> method only handles <code>int</code> values. What if you need to call the method with <code>long</code> arrays? </p> <p> You'd have to add an overload: </p> <p> <pre><strong><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:blue;">long</span>&gt;&nbsp;<span style="color:#74531f;">Consume</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:blue;">long</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">source</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">long</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">quantity</span>) {</strong> <span style="color: silver;">&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(source&nbsp;is&nbsp;null) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;yield&nbsp;break; &nbsp;&nbsp;&nbsp;&nbsp;var&nbsp;accumulator&nbsp;=&nbsp;0L; &nbsp;&nbsp;&nbsp;&nbsp;foreach&nbsp;(var&nbsp;i&nbsp;in&nbsp;source) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(quantity&nbsp;&lt;=&nbsp;accumulator) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;yield&nbsp;return&nbsp;i; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;accumulator&nbsp;+=&nbsp;i; &nbsp;&nbsp;&nbsp;&nbsp;}</span> <strong>}</strong></pre> </p> <p> Do you need support for <code>short</code>? Add an overload. <code>decimal</code>? Add an overload. <code>byte</code>? Add an overload. </p> <p> No wonder people used to dynamic languages find this awkward. </p> <h3 id="bc9ab1e2693d41678a09cf843436c736"> Low ceremony of F# <a href="#bc9ab1e2693d41678a09cf843436c736" title="permalink">#</a> </h3> <p> You can write the same functionality in F#: </p> <p> <pre><strong><span style="color:blue;">let</span>&nbsp;<span style="color:blue;">inline</span></strong><span style="color: silver;">&nbsp;consume&nbsp;quantity&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;let&nbsp;go&nbsp;(acc,&nbsp;xs)&nbsp;x&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;quantity&nbsp;&lt;=&nbsp;acc &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;then&nbsp;(acc,&nbsp;Seq.append&nbsp;xs&nbsp;(Seq.singleton&nbsp;x)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;else&nbsp;(acc&nbsp;+&nbsp;x,&nbsp;xs) &nbsp;&nbsp;&nbsp;&nbsp;Seq.fold&nbsp;go&nbsp;(LanguagePrimitives.GenericZero,&nbsp;Seq.empty)&nbsp;&gt;&gt;&nbsp;snd</span></pre> </p> <p> There's no type declaration in sight, but nonetheless the function is statically typed. It has this somewhat complicated type: </p> <p> <pre>quantity: ^a -&gt; (seq&lt; ^b&gt; -&gt; seq&lt; ^b&gt;) when ( ^a or ^b) : (static member ( + ) : ^a * ^b -&gt; ^a) and ^a : (static member get_Zero : -&gt; ^a) and ^a : comparison</pre> </p> <p> While this looks arcane, it means that it support sequences of any type that comes with a zero value and supports addition and comparison. You can call it with both 32-bit integers, decimals, and so on: </p> <p> <pre>&gt; consume 2 [1;2;3];; val it : seq&lt;int&gt; = seq [3] &gt; consume 2m [1m;2m;3m];; val it : seq&lt;decimal&gt; = seq [3M]</pre> </p> <p> Static typing still means that you can't just call it with any type of value. An expression like <code>consume "foo" [true;false;true]</code> will not compile. </p> <p> You can explicitly declare types in F# (like you can in C#), but my experience is that if you don't, type changes tend to just propagate throughout your code base. Change a type of a function, and upstream callers generally just 'figure it out'. If you think of functions calling other functions as a graph, you often only have to adjust leaf nodes even when you change the type of something deep in your code base. </p> <h3 id="e360bba3f4954f6988fd1267c70b78e1"> Low ceremony of Haskell <a href="#e360bba3f4954f6988fd1267c70b78e1" title="permalink">#</a> </h3> <p> Likewise, you can write the function in Haskell: </p> <p> <pre><span style="color: silver;">consume&nbsp;quantity&nbsp;=&nbsp;reverse&nbsp;.&nbsp;snd&nbsp;.&nbsp;foldl&nbsp;go&nbsp;(0,&nbsp;[]) &nbsp;&nbsp;</span><strong>where</strong><span style="color: silver;"> &nbsp;&nbsp;&nbsp;&nbsp;go&nbsp;(acc,&nbsp;ys)&nbsp;x&nbsp;=&nbsp;if&nbsp;quantity&nbsp;&lt;=&nbsp;acc&nbsp;then&nbsp;(acc,&nbsp;x:ys)&nbsp;else&nbsp;(acc&nbsp;+&nbsp;x,&nbsp;ys)</span></pre> </p> <p> Again, you don't have to explicitly declare any types. The compiler figures them out. You can ask GHCi about the function's type, and it'll tell you: </p> <p> <pre>&gt; :t consume consume :: (Foldable t, Ord a, Num a) =&gt; a -&gt; t a -&gt; [a]</pre> </p> <p> It's more compact than the inferred F# type, but the idea is the same. It'll compile for any <code>Foldable</code> container <code>t</code> and any type <code>a</code> that belongs to the classes of types called <code>Ord</code> and <code>Num</code>. <code>Num</code> supports addition and <code>Ord</code> supports comparison. </p> <p> There's little ceremony involved with the types in Haskell or F#, yet both languages are statically typed. In fact, their type systems are more powerful than C#'s or Java's. They can express relationships between types that those languages can't. </p> <h3 id="d215cd3b1cd84ce3877dc88e8ce944be"> Summary <a href="#d215cd3b1cd84ce3877dc88e8ce944be" title="permalink">#</a> </h3> <p> In debates about static versus dynamic typing, contributors often generalise from their experience with C++, Java, or C#. They dislike the amount of ceremony required in these languages, but falsely believe that it means that you can't have static types without ceremony. </p> <p> The statically typed mainstream languages seem to occupy a <em>Zone of Ceremony</em>. </p> <p> Static typing without ceremony is possible, as evidenced by languages like F# and Haskell. You could call such languages <em>trans-ceremonial languages</em>. They offer the best of both worlds: compile-time checking and little ceremony. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="7ed32b43867d490cad18388ec86baab4"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> In your initial <code>int</code> C# example, I think your point is that method arguments and the return type require <a href="https://en.wikipedia.org/wiki/Manifest_typing">manifest</a> typing. Then for your example about <code>long</code> (and comments about <code>short</code>, <code>decimal</code>, and <code>byte</code>), I think your point is that C#'s type system is primarily <a href="https://en.wikipedia.org/wiki/Nominal_type_system">nominal</a>. You then contrast those C# examples with F# and Haskell examples that utilize <a href="https://en.wikipedia.org/wiki/Type_inference">inferred</a> and <a href="https://en.wikipedia.org/wiki/Structural_type_system">structural</a> aspects of their type systems. </p> <p> I also sometimes get involved in debates about static versus dynamic typing and find myself on the side of static typing. Furthermore, I also typically hear arguments against manifest and nominal typing instead of against static typing. In theory, I agree with those arguments; I also prefer type systems that are inferred and structural instead of those that are manifest and nominal. </p> <p> I see the tradeoff as being among the users of the programming language, those responsible for writing and maintaining the compiler/interpreter, and what can be said about the correctness of the code. (In the rest of this paragraph, all statements about things being simple or complex are meant to be relative. I will also exaggerate for the sake of simplifying my statements.) For a dynamic language, the interpreter and coding are simple but there are no guarantees about correctness. For a static, manifest, and nominal language, the compiler is somewhere between simple and complex, the coding is complex, but at least there are some guarantees about correctness. For a static, inferred, structural language, the compiler is complex, coding is simple, and there are some guarantees about correctness. </p> <p> Contrasting a dynamic language with one that is static, inferred, and structural, I see the tradeoff as being directly between the the compiler/interpreter writers and what can be said about the correctness of the code while the experience of those writing code in the language is mostly unchanged. I think that is your point being made by contrasting the JavaScript example (a dynamic language) with the F# and Haskell examples (that demonstrate the static, inferred, and structural behavior of their type systems). </p> <p> While we are on the topic, I would like to say something that I think is controversial about <a href="https://en.wikipedia.org/wiki/Duck_typing">duck typing</a>. I think duck typing is "just" a dynamic type system that is also structural. This contradicts the lead of its Wikipedia article (linked above) as well as the <a href="https://en.wikipedia.org/wiki/Duck_typing#Structural_type_systems">subsection about structural type systems</a>. They both imply that nominal vs structural typing is a spectrum that only exists for static languages. I disagree; I think dynamic languages can also exist on that spectrum. It is just that most dynamic languages are also structural. In contrast, I think that the manifest vs inferred spectrum exists for static languages but not for dynamic languages. </p> <p> Nonetheless, that subsection makes a great observation. For structural languages, the difference between static and dynamic languages is not just some guarantees about correctness. Dynamic languages check for type correctness at the last possible moment. (That is saying more than saying that the type check happens at runtime.) For example, consider a function with dead code that "doesn't type". If the type system were static, then this function cannot be executed, but if the type system were dynamic, then it could be executed. More practically, suppose the function is a simple <code>if-else</code> statement with code in the <code>else</code> branch that "doesn't type" and that the corresponding Boolean expression always evaluates to <code>true</code>. If the type system were static, then this function cannot be executed, but if the type system were dynamic, then it could be executed. </p> <p> In my experience, the typical solution of a functional programmer would be to strengthen the input types so that the <code>else</code> branch can be proved by the compiler to be dead code and then delete the dead code. This approach makes this one function simpler, and I generally am in favor of this. However, there is a sense in which we can't always repeat this for the calling function. Otherwise, we would end up with a program that is provably correct, which is impossible for a Turning-complete language. Instead, I think the practical solution is to (at some appropriate level) short-circuit the computation when given input that is not known to be good and either do nothing or report back to the user that the input wasn't accepted. </p> </div> <div class="comment-date">2019-12-16 17:12 UTC</div> </div> <div class="comment" id="048a007a6d7f4f67b4ed92b748c78c13"> <div class="comment-author">Romain Deneau <a href="https://twitter.com/DeneauRomain">@DeneauRomain</a></div> <div class="comment-content"> <p> Using mostly both C# and TypeScript, two statically typed languages, I’ve experienced how it’s terser in TypeScript, essentially thanks to its type inference and its structural typing. I like the notion of <em>“Ceremony”</em> you gave to describe this and the fact that it’s not correlated to the kind of typing, dynamic or static 👍 </p> <p> Still, TypeScript is more verbose than F#, as we can see with the following code translation from F# to TypeScript using object literal instead of tuple for the better support of the former: </p> <pre> <span class="hljs-comment" style="color:green;">// const consume = (source: number[], quantity: number): number[]</span> <span class="hljs-keyword" style="color:blue;">const</span> consume = (source: <span class="hljs-built_in" style="color:blue;">number</span>[], quantity: <span class="hljs-built_in" style="color:blue;">number</span>) =&gt;   source.reduce(({ acc, xs }, x) =&gt;     quantity &lt;= acc       ? { acc, xs: xs.concat(x) }       : { acc: acc + x, xs },     { acc: <span class="hljs-number" style="color:purple">0</span>, xs: [] <span class="hljs-keyword" style="color:blue;">as</span> <span class="hljs-built_in" style="color:blue;">number</span>[] }   ).xs;</pre> <p> Checks: </p> <pre> &gt; consume(1, [1,2,3]) [2,3] &gt; consume(2, [1,2,3]) [3] &gt; consume(3, [1,2,3]) [3] &gt; consume(4, [1,2,3]) []</pre> <p> As we can see, the code is a little more verbose than in JavaScript but still terser than in C#. The returned type is inferred as <code>number[]</code> but the <code>as number[]</code> is a pity, necessary because the inferred type of the empty array <code>[]</code> is <code>any[]</code>. </p> <p> <code>consume</code> is not generic: TypeScript/JavaScript as only one primitive for numbers: <code>number</code>. It works for common scenarios but their no simple way to make it work with <code>BigInt</code>, for instance using the union type <code>number | bigint</code>. The more pragmatic option would be to copy-paste, replacing <code>number</code> with <code>bigint</code> and <code>0</code> with <code>0n</code>. </p> </div> <div class="comment-date">2019-12-20 10:10 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Put cyclomatic complexity to good use https://blog.ploeh.dk/2019/12/09/put-cyclomatic-complexity-to-good-use 2019-12-09T14:37:00+00:00 Mark Seemann <div id="post"> <p> <em>An actually useful software metric.</em> </p> <p> In <a href="https://cleancoders.com/video-details/humane-code-real-episode-1">Humane Code</a> I argue that software development suffers from a lack of useful measurements. While I stand by that general assertion, a few code metrics can be useful. <a href="https://en.wikipedia.org/wiki/Cyclomatic_complexity">Cyclomatic complexity</a>, while no <a href="/2019/07/01/yes-silver-bullet">silver bullet</a>, can be put to good use. </p> <h3 id="1462c0daaa1d42eba09691214f9ac8da"> Recap <a href="#1462c0daaa1d42eba09691214f9ac8da" title="permalink">#</a> </h3> <p> I think of cyclomatic complexity as a measure of the number of pathways through a piece of code. Even the simplest body of code affords a single pathway, so the minimum cyclomatic complexity is <em>1</em>. You can easily 'calculate' the cyclomatic complexity of a method for function. You start at one, and then you count how many times <code>if</code> and <code>for</code> occurs. For each of these keywords you find, you increment the number (which started at <em>1</em>). </p> <p> The specifics are language-dependent. The idea is to count branching and looping instructions. In C#, for example, you'd also have to include <code>foreach</code>, <code>while</code>, <code>do</code>, and each <code>case</code> in a <code>switch</code> block. In other languages, the keywords to count will differ. </p> <p> What's the cyclomatic complexity of this <code>TryParse</code> method? </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="color:#74531f;">TryParse</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">candidate</span>,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:#2b91af;">UserNamePassworCredentials</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">credentials</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">credentials</span>&nbsp;=&nbsp;<span style="color:blue;">null</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">arr</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">candidate</span>.<span style="font-weight:bold;color:#74531f;">Split</span>(<span style="color:#a31515;">&#39;,&#39;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">arr</span>.Length&nbsp;&lt;&nbsp;2) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">credentials</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">UserNamePassworCredentials</span>(<span style="font-weight:bold;color:#1f377f;">arr</span>[0],&nbsp;<span style="font-weight:bold;color:#1f377f;">arr</span>[1]); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">true</span>; }</pre> </p> <p> The cyclomatic complexity of this method is <em>2</em>. You start with the number <em>1</em> and then increment it every time you find one of the branching keywords. In this case, there's only a single <code>if</code>, so increment <em>1</em> to <em>2</em>. That's it. If you're in doubt, <a href="https://docs.microsoft.com/en-us/visualstudio/code-quality/code-metrics-values">Visual Studio can calculate metrics for you</a>. (It calculates other metrics as well, but I don't find those useful.) </p> <h3 id="ca340e4d0dbd4391a1e15bd56ab43076"> Guide for unit testing <a href="#ca340e4d0dbd4391a1e15bd56ab43076" title="permalink">#</a> </h3> <p> I find cyclomatic complexity useful because it measures the number of pathways through a method. As such, it indicates the <em>minimum</em> number of test cases you ought to furnish. This is useful when reviewing code and tests. </p> <p> Sometimes I'm presented with code that other people wrote. When I look through the production code, I consider its cyclomatic complexity. If, for example, a method has a cyclomatic complexity of <em>5</em>, I'd expect to find at least five test cases to cover that method. </p> <p> At other times, I start by reading the tests. The number of test cases gives me a rough indication of what degree of complexity to expect. If I see four distinct tests for the same method, I expect it to have a cyclomatic complexity about <em>4</em>. </p> <p> I don't demand 100% coverage. Sometimes, people don't write tests for <a href="https://en.wikipedia.org/wiki/Guard_(computer_science)">guard clauses</a>, and I usually accept such omissions. On the other hand, I think that proper decision logic should be covered by tests. If I were to stick unwaveringly to cyclomatic complexity, that would make my reviews more objective, but not necessarily better. I could insist on 100% code coverage, but <a href="/2015/11/16/code-coverage-is-a-useless-target-measure">I don't consider that a good idea</a>. </p> <p> Presented with the above <code>TryParse</code> method, I'd expect to see at least two unit tests, since the cyclomatic complexity is <em>2</em>. </p> <h3 id="bd88752e8821476984182c968e7a00bb"> The need for more test cases <a href="#bd88752e8821476984182c968e7a00bb" title="permalink">#</a> </h3> <p> Two unit tests aren't enough, though. You could write these two tests: </p> <p> <pre>[<span style="color:#2b91af;">Fact</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">TryParseSucceeds</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">couldParse</span>&nbsp;=&nbsp;<span style="color:#2b91af;">UserNamePassworCredentials</span>.<span style="color:#74531f;">TryParse</span>(<span style="color:#a31515;">&quot;foo,bar&quot;</span>,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">actual</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">True</span>(<span style="font-weight:bold;color:#1f377f;">couldParse</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">expected</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">UserNamePassworCredentials</span>(<span style="color:#a31515;">&quot;foo&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;bar&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">Equal</span>(<span style="font-weight:bold;color:#1f377f;">expected</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">actual</span>); } [<span style="color:#2b91af;">Fact</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">TryParseFails</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">couldParse</span>&nbsp;=&nbsp;<span style="color:#2b91af;">UserNamePassworCredentials</span>.<span style="color:#74531f;">TryParse</span>(<span style="color:#a31515;">&quot;foo&quot;</span>,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">actual</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">False</span>(<span style="font-weight:bold;color:#1f377f;">couldParse</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">Null</span>(<span style="font-weight:bold;color:#1f377f;">actual</span>); }</pre> </p> <p> Using the <a href="/2019/10/07/devils-advocate">Devil's advocate</a> technique, however, this implementation of <code>TryParse</code> passes both tests: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="color:#74531f;">TryParse</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">candidate</span>,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:#2b91af;">UserNamePassworCredentials</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">credentials</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">credentials</span>&nbsp;=&nbsp;<span style="color:blue;">null</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">candidate</span>&nbsp;!=&nbsp;<span style="color:#a31515;">&quot;foo,bar&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">credentials</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">UserNamePassworCredentials</span>(<span style="color:#a31515;">&quot;foo&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;bar&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">true</span>; }</pre> </p> <p> This is clearly not the correct implementation, but it has 100% code coverage. It also still has cyclomatic complexity of <em>2</em>. The metric suggests a <em>minimum</em> number of tests - not a sufficient number. </p> <h3 id="15d3b6efa5f74ab4ba5428d81a9e2443"> More test cases <a href="#15d3b6efa5f74ab4ba5428d81a9e2443" title="permalink">#</a> </h3> <p> It often makes sense to cover each branch with a single parametrised test: </p> <p> <pre>[<span style="color:#2b91af;">Theory</span>] [<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;foo,bar&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;foo&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;bar&quot;</span>)] [<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;baz,qux&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;baz&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;qux&quot;</span>)] [<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;ploeh,fnaah&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;ploeh&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;fnaah&quot;</span>)] [<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;foo,bar,baz&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;foo&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;bar&quot;</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">TryParseSucceeds</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">candidate</span>,&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">userName</span>,&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">password</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">couldParse</span>&nbsp;=&nbsp;<span style="color:#2b91af;">UserNamePassworCredentials</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">candidate</span>,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">actual</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">True</span>(<span style="font-weight:bold;color:#1f377f;">couldParse</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">expected</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">UserNamePassworCredentials</span>(<span style="font-weight:bold;color:#1f377f;">userName</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">password</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">Equal</span>(<span style="font-weight:bold;color:#1f377f;">expected</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">actual</span>); } [<span style="color:#2b91af;">Theory</span>] [<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;&quot;</span>)] [<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;foobar&quot;</span>)] [<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;foo;bar&quot;</span>)] [<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;foo&quot;</span>)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">TryParseFails</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">candidate</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">couldParse</span>&nbsp;=&nbsp;<span style="color:#2b91af;">UserNamePassworCredentials</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">candidate</span>,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">actual</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">False</span>(<span style="font-weight:bold;color:#1f377f;">couldParse</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">Null</span>(<span style="font-weight:bold;color:#1f377f;">actual</span>); }</pre> </p> <p> Is a total of eight test cases the correct number? Cyclomatic complexity can't help you here. You'll have to rely on other heuristics, such as test-driven development, the <a href="https://blog.cleancoder.com/uncle-bob/2013/05/27/TheTransformationPriorityPremise.html">transformation priority premise</a>, and the Devil's Advocate. </p> <h3 id="a8b2fa3d0101430d871b99a4bab136b7"> Humane Code <a href="#a8b2fa3d0101430d871b99a4bab136b7" title="permalink">#</a> </h3> <p> I also find cyclomatic complexity useful for another reason. I keep an eye on complexity because I care about code maintainability. In my <a href="https://cleancoders.com/video-details/humane-code-real-episode-1">Humane Code</a> video, I discuss <a href="https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two">the magic number seven, plus or minus two</a>. </p> <p> When you read code, you essentially run a little emulator in your brain. You have to maintain state in order to interpret the code you look at. <em>Will this conditional evaluate to true or false? Is the code going to exit that loop now? Is that array index out of bounds?</em> You can only follow the code by keeping track of variables' contents, and your brain can keep track of approximately seven things. </p> <p> Cyclomatic complexity is a measure of pathways - not how many things you need to keep track of. Still, in my experience, there seems to be a useful correlation. Code with high cyclomatic complexity tends to have many moving parts. There's too much to keep track of. With low cyclomatic complexity, on the other hand, the code involves few moving parts. </p> <p> I use cyclomatic complexity <em>7</em> as an approximate maximum for that reason. It's only a rule of thumb, since I'm painfully aware that I'm transplanting experimental psychology to a context where no conclusions can be scientifically drawn. But like <a href="/2019/11/04/the-80-24-rule">the 80/24 rule</a> I find that it works well in practice. </p> <h3 id="de927bfcc95d410bbfcd0adf7a63926b"> Complexity of a method call <a href="#de927bfcc95d410bbfcd0adf7a63926b" title="permalink">#</a> </h3> <p> Consider the above parametrised tests. Some of the test cases provide enough triangulation to defeat the Devil's attempt at hard-coding return values. This explains test values like <code>"foo,bar"</code>, <code>"baz,qux"</code>, and <code>"ploeh,fnaah"</code>, but why did I include the <code>"foo,bar,baz"</code> test case? And why did I include the empty string as one of the test cases for <code>TryParseFails</code>? </p> <p> When I write tests, I aspire to compose tests that verify the behaviour rather than the implementation of the System Under Test. The desired behaviour, I decided, is that any extra entries in the comma-separated input should be ignored. Likewise, if there's fewer than two entries, parsing should fail. There must be both a user name and a password. </p> <p> Fortunately, this happens to be how <a href="https://docs.microsoft.com/dotnet/api/system.string.split">Split</a> already works. If you consider all the behaviour that <code>Split</code> exhibits, it encapsulates moderate complexity. It can split on multiple alternative delimiters, it can throw away empty entries, and so on. What would happen if you inline some of that functionality? </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="color:#74531f;">TryParse</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">candidate</span>,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:#2b91af;">UserNamePassworCredentials</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">credentials</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">credentials</span>&nbsp;=&nbsp;<span style="color:blue;">null</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">l</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">List</span>&lt;<span style="color:blue;">string</span>&gt;(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">element</span>&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">c</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">in</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">candidate</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">c</span>&nbsp;==&nbsp;<span style="color:#a31515;">&#39;,&#39;</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">l</span>.<span style="font-weight:bold;color:#74531f;">Add</span>(<span style="font-weight:bold;color:#1f377f;">element</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">element</span>&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">else</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">element</span>&nbsp;+=&nbsp;<span style="font-weight:bold;color:#1f377f;">c</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">l</span>.<span style="font-weight:bold;color:#74531f;">Add</span>(<span style="font-weight:bold;color:#1f377f;">element</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">l</span>.Count&nbsp;&lt;&nbsp;2) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">credentials</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">UserNamePassworCredentials</span>(<span style="font-weight:bold;color:#1f377f;">l</span>[0],&nbsp;<span style="font-weight:bold;color:#1f377f;">l</span>[1]); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">true</span>; }</pre> </p> <p> This isn't as sophisticated as the <code>Split</code> method it replaces, but it passes all eight test cases. Why did I do this? To illustrate the following point. </p> <p> What's the cyclomatic complexity now? </p> <p> Keep in mind that the externally observable behaviour (as defined by eight test cases) hasn't changed. The cyclomatic complexity, however, has. It's now <em>4</em> - double the previous metric. </p> <p> A method call (like a call to <code>Split</code>) can hide significant cyclomatic complexity. That's a desirable situation. This is the benefit that <a href="/encapsulation-and-solid">encapsulation</a> offers: that you don't have to worry about implementation details as long as both caller and callee fulfils the contract. </p> <p> When you calculate cyclomatic complexity, a method call doesn't increment the complexity, regardless of the degree of complexity that it encapsulates. </p> <h3 id="10a3f65b7bf54b04b35b8e69552803b9"> Summary <a href="#10a3f65b7bf54b04b35b8e69552803b9" title="permalink">#</a> </h3> <p> Cyclomatic complexity is one of the rare programming metrics that I find useful. It measures the number of pathways through a body of code. </p> <p> You can use it to guide your testing efforts. The number is the minimum number of tests you must write in order to cover all branches. You'll likely need more test cases than that. </p> <p> You can also <a href="/2020/04/13/curb-code-rot-with-thresholds">use the number as a threshold</a>. I suggest that <em>7</em> ought to be the maximum cyclomatic complexity of a method or function. You're welcome to pick another number, but keeping an eye on cyclomatic complexity is useful. It tells you when it's time to refactor a complex method. </p> <p> Cyclomatic complexity considers only the code that directly implements a method or function. That code can call other code, but what happens behind a method call doesn't impact the metric. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="6fa1adc55d8841918b27599749283abd"> <div class="comment-author">Ghillie Dhu</div> <div class="comment-content"> <p> Do you know of a tool to calculate cyclomatic complexity for F#? It appears that the Visual Studio feature doesn't support it. </p> </div> <div class="comment-date">2019-12-09 19:20 UTC</div> </div> <div class="comment" id="1caf28073f484530ad8389f44ad4a531"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Ghillie, thank you for writing. I'm not aware of any such tool. </p> <p> FWIW, it's not difficult to manually calculate cyclometric complexity for F#, but clearly that doesn't help if you'd like to automate the process. </p> <p> It might be a fine project for anyone looking for a way to contribute to the F# ecosystem. </p> </div> <div class="comment-date">2019-12-09 20:06 UTC</div> </div> <div class="comment" id="ab53d55f92eb4acea0a896436294f3af"> <div class="comment-author">Carlos Schults</div> <div class="comment-content"> <p> Hi, Mark. Thanks for your article. I'd commenting because I'd like to learn more about your thoughts on mutation testing. I ask this because I know you're not the biggest fan of code coverage as a useful metric. I'm not either, or at least I wasnt, until I learned about mutation testing. </p> <p>My current view is that code coverage is only (mostly) meaningless if you don't have a way of measuring the quality of the tests. Since mutation testing's goal is exactly that (to test the tests, if you will) my opinion is that, if you use a mutation testing tool, then code coverage become really useful and you should try to get to 100%. I've even written a <a href="https://blog.ncrunch.net/post/mutation-testing-code-coverage.aspx">post about this subject.</a></p> <p>So, in short: what are your thoughts on mutation testing and how it affects the meaning of code coverage, if at all? Looking forward to read your answer. A whole post on this would be even better! </p> <p>Thanks!</p> </div> <div class="comment-date">2019-12-14 12:32 UTC</div> </div> <div class="comment" id="4b240074da164f87bfabcc484a2b8c7b"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Carlos, thank you for writing. I'm sympathetic to the idea of mutation testing, but apart from that, I have no opinion of it. I don't think that I ought to have an opinion about something with which I've no experience. </p> <p> I first heard about mutation testing decades ago, but I've never come across a mutation testing tool for C# (or F#, for that matter). Can you recommend one? </p> </div> <div class="comment-date">2019-12-14 13:51 UTC</div> </div> <div class="comment" id="46eafa3c33ba47b1bacd997f7e217c4f"> <div class="comment-author">Carlos Schults</div> <div class="comment-content"> <p> Unfortunately, tooling is indeed one of the main Achilles heels of mutation testing, at least when it comes to .NET. </p> <p> In the Java world, they have <a href="https://pitest.org/">PIT</a>, which is considered state of the art. For C#, I have tried a few tools, with no success. The most promising solution I've found so far, for C#, is <a href="https://stryker-mutator.io/stryker-net/">Stryker.net</a>, which is a port of the Stryker mutation, designed originally for JavaScript. The C# version is still in its early phases but it's already usable and it looks very promising. </p> </div> <div class="comment-date">2019-12-14 16:16 UTC</div> </div> <div class="comment" id="32db969bac2d466a9be05111cc505f9d"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> Is mutation testing the automated version of what Mark has called the <a href="/2019/10/07/devils-advocate">Devil's Advocate technique</a>? </p> </div> <div class="comment-date">2019-12-15 02:26 UTC</div> </div> <div class="comment" id="c889aa4c4ee04df38e8954afc30e6a6f"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, I actually <a href="/2019/10/07/devils-advocate#26be7b38248c4dcba5134eb4529d8214">discuss the relationship with mutation testing</a> in that article. </p> </div> <div class="comment-date">2019-12-15 9:28 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Refactoring registration flow to functional architecture https://blog.ploeh.dk/2019/12/02/refactoring-registration-flow-to-functional-architecture 2019-12-02T08:19:00+00:00 Mark Seemann <div id="post"> <p> <em>An example showing a refactoring from F# partial application 'dependency injection' to an impure/pure/impure sandwich.</em> </p> <p> In <a href="/2017/02/02/dependency-rejection#36c724b49f614104842c47909cd9c916">a comment</a> to <a href="/2017/02/02/dependency-rejection">Dependency rejection</a>, I wrote: <blockquote> "I'd welcome a simplified, but still concrete example where the impure/pure/impure sandwich described here isn't going to be possible." </blockquote> <a href="https://www.relativisticramblings.com">Christer van der Meeren</a> kindly <a href="/2017/02/02/dependency-rejection#ade3787e6e3c4e569854e2c2bd038e29">replied with a suggestion.</a> </p> <p> The code in question relates to validation of user accounts. You can read the complete description in the linked comment, but I'll try to summarise it here. I'll then show a refactoring to a <a href="/2018/11/19/functional-architecture-a-definition">functional architecture</a> - specifically, to an impure/pure/impure sandwich. </p> <p> The code is <a href="https://github.com/ploeh/RegistrationFlow">available on GitHub</a>. </p> <h3 id="53c0b4111cf640e0b6fd13066e24f3bd"> Registration flow <a href="#53c0b4111cf640e0b6fd13066e24f3bd" title="permalink">#</a> </h3> <p> The system in question uses two-factor authentication with mobile phones. When you sign up for the service, you give your phone number. You then receive an SMS, and must use whatever is in that SMS to prove ownership of the phone number. Christer van der Meeren illustrates the flow like this: </p> <p> <img src="/content/binary/complete-registration-workflow-with-2fa-difficult-to-sandwich.png" alt="A flowchart describing the workflow for completing a registration."> </p> <p> He also supplies sample code: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;completeRegistrationWorkflow &nbsp;&nbsp;&nbsp;&nbsp;(createProof:&nbsp;Mobile&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Async&lt;ProofId&gt;) &nbsp;&nbsp;&nbsp;&nbsp;(verifyProof:&nbsp;Mobile&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;ProofId&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Async&lt;bool&gt;) &nbsp;&nbsp;&nbsp;&nbsp;(completeRegistration:&nbsp;Registration&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Async&lt;unit&gt;) &nbsp;&nbsp;&nbsp;&nbsp;(proofId:&nbsp;ProofId&nbsp;option) &nbsp;&nbsp;&nbsp;&nbsp;(registration:&nbsp;Registration) &nbsp;&nbsp;&nbsp;&nbsp;:&nbsp;Async&lt;CompleteRegistrationResult&gt;&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;proofId&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;None&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;proofId&nbsp;=&nbsp;createProof&nbsp;registration.Mobile &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;ProofRequired&nbsp;proofId &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;proofId&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;isValid&nbsp;=&nbsp;verifyProof&nbsp;registration.Mobile&nbsp;proofId &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;isValid&nbsp;<span style="color:blue;">then</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;completeRegistration&nbsp;registration &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;RegistrationCompleted &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;proofId&nbsp;=&nbsp;createProof&nbsp;registration.Mobile &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;ProofRequired&nbsp;proofId &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> While this is <a href="https://fsharp.org">F#</a>, it's not functional, since it uses <a href="/2017/01/30/partial-application-is-dependency-injection">partial application for dependency injection</a>. From the description, I find it safe to assume that we can consider <a href="/2016/04/11/async-as-surrogate-io">Async as a surrogate for IO</a>. </p> <p> The code implies the existence of other types. I decided to define them like this: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;Mobile&nbsp;=&nbsp;Mobile&nbsp;<span style="color:blue;">of</span>&nbsp;int <span style="color:blue;">type</span>&nbsp;ProofId&nbsp;=&nbsp;ProofId&nbsp;<span style="color:blue;">of</span>&nbsp;Guid <span style="color:blue;">type</span>&nbsp;Registration&nbsp;=&nbsp;{&nbsp;Mobile&nbsp;:&nbsp;Mobile&nbsp;} <span style="color:blue;">type</span>&nbsp;CompleteRegistrationResult&nbsp;=&nbsp;ProofRequired&nbsp;<span style="color:blue;">of</span>&nbsp;ProofId&nbsp;|&nbsp;RegistrationCompleted</pre> </p> <p> In reality, they're probably more complicated, but this is enough to make the code compile. </p> <p> Is it possible to refactor <code>completeRegistrationWorkflow</code> to an impure/pure/impure sandwich? </p> <h3 id="3266f23516dc4d9e98f3a8c87d072f89"> Applicability <a href="#3266f23516dc4d9e98f3a8c87d072f89" title="permalink">#</a> </h3> <p> It <em>is</em> possible to refactor <code>completeRegistrationWorkflow</code> to an impure/pure/impure sandwich. You'll see how to do that soon. Before we start that work, however, I'd like to warn against jumping to conclusions. It's possible that the problem statement doesn't capture some subtleties that one would have to deal with in the real world. It's also possible that I've misunderstood the essence of Christer van der Meeren's problem description. </p> <p> It's (relatively) easy to teach the basics of programming. You teach a beginner about keywords, programming constructs, how to compile or interpret a program, and so on. </p> <p> On the other hand, it's hard to write about dealing with complicated code. There are ways to make legacy code better, but the moves you have to make depend on myriad details. Complicated code is, by definition, something that's hard to learn. This means that truly complicated legacy code is rarely suitable for instructive examples. One has to strike a delicate balance and produce an example that looks complicated enough to warrant improvement, but on the other hand still be simple enough to be understood. </p> <p> I think that Christer van der Meeren has struck that balance. With three dependencies, the sample code looks just complicated enough to warrant refactoring. On the other hand, you can understand what it's supposed to do in a few minutes. There's a risk, however, that the example is <em>too</em> simplified. That could weaken the result of the refactoring that follows. Could you still apply that refactoring if the problem was more complicated? </p> <p> It's my experience that it's conspicuously often possible to implement an impure/pure/impure sandwich. </p> <h3 id="fedd0146b0a84ab3b768f3adcf4f684f"> Fakes <a href="#fedd0146b0a84ab3b768f3adcf4f684f" title="permalink">#</a> </h3> <p> In the rest of this article, I want to show how to refactor <code>completeRegistrationWorkflow</code> to an impure/pure/impure sandwich. As <a href="http://amzn.to/YPdQDf">Refactoring</a> admonishes: <blockquote> <p> "to refactor, the essential precondition is [...] solid tests" </p> <footer><cite>Martin Fowler</cite></footer> </blockquote> Right now, however, there's no tests, so I'm going to add some. </p> <p> The tests will need some <a href="https://en.wikipedia.org/wiki/Test_double">Test Doubles</a> to stand in for the three dependency functions. If possible, <a href="/2019/03/25/an-example-of-state-based-testing-in-f">I prefer state-based testing</a> over <a href="/2019/02/25/an-example-of-interaction-based-testing-in-c">interaction-based testing</a>. First, then, we need some Fakes. </p> <p> While <code>completeRegistrationWorkflow</code> takes three dependency functions, it looks as though there's only two architectural dependencies: <ul> <li>A two-factor authentication service</li> <li>A registration database (or service)</li> </ul> Defining a Fake two-factor authentication object is the most complicated of the two, but still manageable: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;Fake2FA&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:blue;">mutable</span>&nbsp;proofs&nbsp;=&nbsp;Map.empty &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;_.CreateProof&nbsp;mobile&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;Map.tryFind&nbsp;mobile&nbsp;proofs&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;(proofId,&nbsp;_)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;proofId &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;None&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;proofId&nbsp;=&nbsp;ProofId&nbsp;(Guid.NewGuid&nbsp;()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;proofs&nbsp;<span style="color:blue;">&lt;-</span>&nbsp;Map.add&nbsp;mobile&nbsp;(proofId,&nbsp;<span style="color:blue;">false</span>)&nbsp;proofs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;proofId &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:blue;">fun</span>&nbsp;proofId&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;async&nbsp;{&nbsp;<span style="color:blue;">return</span>&nbsp;proofId&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;_.VerifyProof&nbsp;mobile&nbsp;proofId&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;Map.tryFind&nbsp;mobile&nbsp;proofs&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;(_,&nbsp;<span style="color:blue;">true</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">true</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">false</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:blue;">fun</span>&nbsp;b&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;async&nbsp;{&nbsp;<span style="color:blue;">return</span>&nbsp;b&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;_.VerifyMobile&nbsp;mobile&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;Map.tryFind&nbsp;mobile&nbsp;proofs&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;(proofId,&nbsp;_)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;proofs&nbsp;<span style="color:blue;">&lt;-</span>&nbsp;Map.add&nbsp;mobile&nbsp;(proofId,&nbsp;<span style="color:blue;">true</span>)&nbsp;proofs &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;()</pre> </p> <p> In F#, I find that the easiest way to model a mutable resource is to use an object. This one just keeps track of a collection of proofs. The <code>CreateProof</code> method fits the function signature of <code>completeRegistrationWorkflow</code>'s <code>createProof</code> function argument. It looks for an existing proof for the mobile number so that it can reuse the same proof multiple times. If there's no proof for <code>mobile</code>, it creates a new <code>Guid</code> and returns it after having first added it to the collection. </p> <p> Likewise, the <code>VerifyProof</code> method fits the type of the <code>verifyProof</code> function argument. Proofs are actually tuples of IDs and a flag that keeps track of whether or not they've been verified. The method returns the flag if it's there, and <code>false</code> otherwise. </p> <p> The third <code>VerifyMobile</code> method is a test-specific functionality that enables a test to mark a proof as having been verified via two-factor authentication. </p> <p> Compared to <code>Fake2FA</code>, the Fake registration database is simple: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;FakeRegistrationDB&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;Collection&lt;Registration&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.CompleteRegistration&nbsp;r&nbsp;=&nbsp;async&nbsp;{&nbsp;this.Add&nbsp;r&nbsp;}</pre> </p> <p> Again, the <code>CompleteRegistration</code> method fits the <code>completeRegistration</code> function argument to <code>completeRegistrationWorkflow</code>. It just makes the inherited <code>Add</code> method <code>Async</code>. </p> <h3 id="8dbbe25d331f4517b3fe8ace6e95ffa9"> Fixture creation <a href="#8dbbe25d331f4517b3fe8ace6e95ffa9" title="permalink">#</a> </h3> <p> My plan is to add <a href="https://en.wikipedia.org/wiki/Characterization_test">Characterisation Tests</a> so that I can refactor. I do, however, plan to change the API of the System Under Test (SUT). This could break the tests, which would defy their purpose. To protect against this, I'll test against a <a href="https://en.wikipedia.org/wiki/Facade_pattern">Facade</a>. Initially, this Facade will be equivalent to the <code>completeRegistrationWorkflow</code> function, but this will change as I refactor. </p> <p> In addition to the SUT Facade, the tests will also need access to the 'injected' dependencies. You can address this by creating a <a href="/2009/03/16/FixtureObject">Fixture Object</a>: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;createFixture&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;twoFA&nbsp;=&nbsp;Fake2FA&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;db&nbsp;=&nbsp;FakeRegistrationDB&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;sut&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;completeRegistrationWorkflow &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;twoFA.CreateProof &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;twoFA.VerifyProof &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;db.CompleteRegistration &nbsp;&nbsp;&nbsp;&nbsp;sut,&nbsp;twoFA,&nbsp;db</pre> </p> <p> This function return a triple of values: the SUT Facade and the two Fakes. </p> <p> The SUT Facade is a partially applied function of the type <code>ProofId option -&gt; Registration -&gt; Async&lt;CompleteRegistrationResult&gt;</code>. In other words, it abstracts away the specifics about how impure actions are executed. It seems reasonable to imagine that the two remaining input arguments, <code>ProofId option</code> and <code> Registration</code>, are run-time values. Regardless of refactoring, the resulting function should be able to receive those arguments and produce the desired outcome. </p> <h3 id="a6dbde952b53422992ae006bdc305053"> Characterising the missing proof ID case <a href="#a6dbde952b53422992ae006bdc305053" title="permalink">#</a> </h3> <p> It looks like the <a href="https://en.wikipedia.org/wiki/Cyclomatic_complexity">cyclomatic complexity</a> of <code>completeRegistrationWorkflow</code> is <em>3</em>, so you're going to need three Characterisation Tests. You can add them in any order you like, but in this case I found it natural to follow the order in which the branches are laid out in the SUT. </p> <p> This test case verifies what happens if the proof ID is missing: </p> <p> <pre>[&lt;Theory&gt;] [&lt;InlineData&nbsp;123&gt;] [&lt;InlineData&nbsp;432&gt;] <span style="color:blue;">let</span>&nbsp;``Missing&nbsp;proof&nbsp;ID``&nbsp;mobile&nbsp;=&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;sut,&nbsp;twoFA,&nbsp;db&nbsp;=&nbsp;createFixture&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;r&nbsp;=&nbsp;{&nbsp;Mobile&nbsp;=&nbsp;Mobile&nbsp;mobile&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;actual&nbsp;=&nbsp;sut&nbsp;None&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;expectedProofId&nbsp;=&nbsp;twoFA.CreateProof&nbsp;r.Mobile &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;expected&nbsp;=&nbsp;ProofRequired&nbsp;expectedProofId &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;actual &nbsp;&nbsp;&nbsp;&nbsp;test&nbsp;&lt;@&nbsp;Seq.isEmpty&nbsp;db&nbsp;@&gt;&nbsp;}</pre> </p> <p> All the tests in this article use <a href="https://xunit.net">xUnit.net</a> 2.4.0 with <a href="https://github.com/SwensenSoftware/unquote">Unquote</a> 5.0.0. </p> <p> This test calls the <code>sut</code> Facade with a <code>None</code> proof ID and an arbitrary <code>Registration</code> <code>r</code>. Had I used a <a href="/property-based-testing-intro">property-based testing</a> framework such as <a href="https://fscheck.github.io/FsCheck">FsCheck</a> or <a href="https://github.com/hedgehogqa/fsharp-hedgehog">Hedgehog</a>, I could have made the <code>Registration</code> value itself an arbitrary test argument, but I thought that this was overkill for this situation. </p> <p> In order to figure out the <code>expectedProofId</code>, the test relies on the behaviour of the <code>Fake2FA</code> class. The <code>CreateProof</code> method is <a href="https://en.wikipedia.org/wiki/Idempotence">idempotent</a>, so calling it several times with the same number should return the same proof. In this test case, we expect the <code>sut</code> to have done so already, so calling the method once more from the test should return the same value that the SUT received. The test then wraps the proof ID in the <code>ProofRequired</code> case and uses Unquote's <code>=!</code> (<em>must equal</em>) operator to verify that <code>expected</code> is equal to <code>actual</code>. </p> <p> Finally, the test also verifies that the reservations database remains empty. </p> <p> Since this is a Characterisation Test it already passes, <a href="/2013/04/02/why-trust-tests">which makes it untrustworthy</a>. How do I know that I didn't write a <a href="/2019/10/14/tautological-assertion">Tautological Assertion</a>? </p> <p> When I write Characterisation Tests, I always try to change the SUT to verify that the test fails for the appropriate reason. In order to fail the first assertion, I can make this change to the <code>None</code> branch of the SUT: </p> <p> <pre><span style="color:blue;">match</span>&nbsp;proofId&nbsp;<span style="color:blue;">with</span> |&nbsp;None&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//let!&nbsp;proofId&nbsp;=&nbsp;createProof&nbsp;registration.Mobile</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;proofId&nbsp;=&nbsp;ProofId&nbsp;(Guid.NewGuid&nbsp;()) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;ProofRequired&nbsp;proofId</pre> </p> <p> This fails the <code>expected =! actual</code> assertion, as expected. </p> <p> Likewise, you can fail the second assertion with this change: </p> <p> <pre><span style="color:blue;">match</span>&nbsp;proofId&nbsp;<span style="color:blue;">with</span> |&nbsp;None&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;completeRegistration&nbsp;registration &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;proofId&nbsp;=&nbsp;createProof&nbsp;registration.Mobile &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;ProofRequired&nbsp;proofId</pre> </p> <p> The addition of the <code>completeRegistration</code> statement causes the <code>test &lt;@ Seq.isEmpty db @&gt;</code> assertion to fail, again as expected. </p> <p> Now I trust that test. </p> <h3 id="a9dceb6d72af4d06bc46bae83464b201"> Characterising the valid proof ID case <a href="#a9dceb6d72af4d06bc46bae83464b201" title="permalink">#</a> </h3> <p> Next, you have the case where all is good. The proof ID is present and valid. You can characterise the behaviour with this test: </p> <p> <pre>[&lt;Theory&gt;] [&lt;InlineData&nbsp;987&gt;] [&lt;InlineData&nbsp;247&gt;] <span style="color:blue;">let</span>&nbsp;``Valid&nbsp;proof&nbsp;ID``&nbsp;mobile&nbsp;=&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;sut,&nbsp;twoFA,&nbsp;db&nbsp;=&nbsp;createFixture&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;r&nbsp;=&nbsp;{&nbsp;Mobile&nbsp;=&nbsp;Mobile&nbsp;mobile&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;p&nbsp;=&nbsp;twoFA.CreateProof&nbsp;r.Mobile &nbsp;&nbsp;&nbsp;&nbsp;twoFA.VerifyMobile&nbsp;r.Mobile &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;actual&nbsp;=&nbsp;sut&nbsp;(Some&nbsp;p)&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;RegistrationCompleted&nbsp;=!&nbsp;actual &nbsp;&nbsp;&nbsp;&nbsp;test&nbsp;&lt;@&nbsp;Seq.contains&nbsp;r&nbsp;db&nbsp;@&gt;&nbsp;}</pre> </p> <p> This test uses <code>CreateProof</code> to create a proof before the <code>sut</code> is exercised. It also uses the test-specific <code>VerifyMobile</code> method to mark the mobile number (and thereby the proof) as valid. </p> <p> Again, there's two assertions: one against the return value <code>actual</code>, and one that verifies that the registration database <code>db</code> now contains the registration <code>r</code>. </p> <p> As before, you can't trust a Characterisation Test before you've seen it fail, so first edit the <code>isValid</code> branch of the SUT like this: </p> <p> <pre><span style="color:blue;">if</span>&nbsp;isValid&nbsp;<span style="color:blue;">then</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;completeRegistration&nbsp;registration &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//return&nbsp;RegistrationCompleted</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;ProofRequired&nbsp;proofId</pre> </p> <p> This fails the <code>RegistrationCompleted =! actual</code> assertion, as expected. </p> <p> Now make this change: </p> <p> <pre><span style="color:blue;">if</span>&nbsp;isValid&nbsp;<span style="color:blue;">then</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//do!&nbsp;completeRegistration&nbsp;registration</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;RegistrationCompleted</pre> </p> <p> Now the <code>test &lt;@ Seq.contains r db @&gt;</code> assertion fails, as expected. </p> <p> This test also seems trustworthy. </p> <h3 id="a4f44c3575914d628931c88095df477e"> Characterising the invalid proof ID case <a href="#a4f44c3575914d628931c88095df477e" title="permalink">#</a> </h3> <p> The final test case is when a proof ID exists, but it's invalid: </p> <p> <pre>[&lt;Theory&gt;] [&lt;InlineData&nbsp;327&gt;] [&lt;InlineData&nbsp;666&gt;] <span style="color:blue;">let</span>&nbsp;``Invalid&nbsp;proof&nbsp;ID``&nbsp;mobile&nbsp;=&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;sut,&nbsp;twoFA,&nbsp;db&nbsp;=&nbsp;createFixture&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;r&nbsp;=&nbsp;{&nbsp;Mobile&nbsp;=&nbsp;Mobile&nbsp;mobile&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;p&nbsp;=&nbsp;twoFA.CreateProof&nbsp;r.Mobile &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;actual&nbsp;=&nbsp;sut&nbsp;(Some&nbsp;p)&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;expectedProofId&nbsp;=&nbsp;twoFA.CreateProof&nbsp;r.Mobile &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;expected&nbsp;=&nbsp;ProofRequired&nbsp;expectedProofId &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;actual &nbsp;&nbsp;&nbsp;&nbsp;test&nbsp;&lt;@&nbsp;Seq.isEmpty&nbsp;db&nbsp;@&gt;&nbsp;}</pre> </p> <p> The <a href="/2013/06/24/a-heuristic-for-formatting-code-according-to-the-aaa-pattern">arrange phase</a> of the test is comparable to the previous test case. The only difference is that the new test <em>doesn't</em> invoke <code>twoFA.VerifyMobile r.Mobile</code>. This leaves the generated proof ID <code>p</code> invalid. </p> <p> The assertions, on the other hand, are identical to those of the <code>Missing proof ID</code> test case, which means that you can make the same edits to the <code>else</code> branch as you can to the <code>None</code> branch, as described above. If you do that, the assertions fail as they're supposed to. You can also trust this Characterisation Test. </p> <h3 id="3f733ce502814d458395b3561c63b897"> Eta expansion <a href="#3f733ce502814d458395b3561c63b897" title="permalink">#</a> </h3> <p> While I want to keep the SUT Facade's type unchanged, I do want change the way I compose it. The goal is an impure/pure/impure sandwich: Do something impure first, then call a pure function with the data obtained, and finally do something impure with the output of the pure function. </p> <p> This means that the composition is going to manipulate the input values to the SUT Facade. To make that easier, I perform an <em>eta conversion</em> on the <code>sut</code>: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;createFixture&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;twoFA&nbsp;=&nbsp;Fake2FA&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;db&nbsp;=&nbsp;FakeRegistrationDB&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;sut&nbsp;pid&nbsp;r&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;completeRegistrationWorkflow &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;twoFA.CreateProof &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;twoFA.VerifyProof &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;db.CompleteRegistration &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pid &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;sut,&nbsp;twoFA,&nbsp;db</pre> </p> <p> This doesn't change the behaviour or how the SUT is composed. It only makes the <code>pid</code> and <code>r</code> arguments explicitly visible. </p> <h3 id="9afbddfce5e14b3c98435a9d2e3f6848"> Move proof verification <a href="#9afbddfce5e14b3c98435a9d2e3f6848" title="permalink">#</a> </h3> <p> When you consider the current implementation of <code>completeRegistrationWorkflow</code>, it seems that the impure actions are interleaved with the decision-making code. How to separate them? </p> <p> The first opportunity that I identified was that it always calls <code>verifyProof</code> in the <code>Some</code> case. Whenever you want to call a method only in the <code>Some</code> case, but not in the <code>None</code> case, it suggest <code>Option.map</code>. </p> <p> It should be possible to run <code>Option.map (twoFA.VerifyProof r.Mobile) pid</code> as the initial impure action of the impure/pure/impure sandwich. If that's possible, we could pass the output of that pure function as an argument to <code>completeRegistrationWorkflow</code>. That would already make it simpler: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;completeRegistrationWorkflow &nbsp;&nbsp;&nbsp;&nbsp;(createProof:&nbsp;Mobile&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Async&lt;ProofId&gt;) &nbsp;&nbsp;&nbsp;&nbsp;(completeRegistration:&nbsp;Registration&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Async&lt;unit&gt;) &nbsp;&nbsp;&nbsp;&nbsp;(proof:&nbsp;bool&nbsp;option) &nbsp;&nbsp;&nbsp;&nbsp;(registration:&nbsp;Registration) &nbsp;&nbsp;&nbsp;&nbsp;:&nbsp;Async&lt;CompleteRegistrationResult&gt;&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;proof&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;None&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;proofId&nbsp;=&nbsp;createProof&nbsp;registration.Mobile &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;ProofRequired&nbsp;proofId &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;isValid&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;isValid&nbsp;<span style="color:blue;">then</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;completeRegistration&nbsp;registration &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;RegistrationCompleted &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;proofId&nbsp;=&nbsp;createProof&nbsp;registration.Mobile &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;ProofRequired&nbsp;proofId &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> Notice that by changing the <code>proof</code> argument to a <code>bool option</code>, you no longer need to call <code>verifyProof</code>, so you can remove it. </p> <p> There's just one problem. The result of <code>Option.map (twoFA.VerifyProof r.Mobile) pid</code> is an <code>Option&lt;Async&lt;bool&gt;&gt;</code>, but you need an <code>Option&lt;bool&gt;</code>. </p> <p> You can compose the SUT Facade in an asynchronous workflow, and use a <code>let!</code> binding, but that's not going to solve the problem. A <code>let!</code> binding only works when the outer container is <code>Async</code>. Here, the outermost container is <code>Option</code>. You're going to need to flip the containers around so that you get an <code>Async&lt;Option&lt;bool&gt;&gt;</code> that you can <code>let!</code>-bind: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;sut&nbsp;pid&nbsp;r&nbsp;=&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;p&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;Option.map&nbsp;(twoFA.VerifyProof&nbsp;r.Mobile)&nbsp;pid&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;b&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;b&#39;&nbsp;=&nbsp;b &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;Some&nbsp;b&#39;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;None&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;async&nbsp;{&nbsp;<span style="color:blue;">return</span>&nbsp;None&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return!</span>&nbsp;completeRegistrationWorkflow &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;twoFA.CreateProof &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;db.CompleteRegistration &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;p &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> By pattern-matching on <code>Option.map (twoFA.VerifyProof r.Mobile) pid</code>, you can return one of two alternative asynchronous workflows. </p> <p> Due to the <code>let!</code> binding, <code>p</code> is a <code>bool option</code> that you can pass to <code>completeRegistrationWorkflow</code>. </p> <h3 id="a271fa42747a4271a5420951763d3559"> Traversal <a href="#a271fa42747a4271a5420951763d3559" title="permalink">#</a> </h3> <p> I know what you're going to say. You'll protest that I just moved complex behaviour out of <code>completeRegistrationWorkflow</code>. The implied assumption here is that <code>completeRegistrationWorkflow</code> is the top-level behaviour that you'd compose in a <a href="/2011/07/28/CompositionRoot">Composition Root</a>. The <code>createFixture</code> function plays that role in this refactoring exercise. </p> <p> You'd normally view the Composition Root as a <a href="http://xunitpatterns.com/Humble%20Object.html">Humble Object</a> - an object that we accept isn't covered by tests because it has a cyclomatic complexity of one. This is no longer the case. </p> <p> The conversion of <code>Option&lt;Async&lt;bool&gt;&gt;</code> to <code>Async&lt;Option&lt;bool&gt;&gt;</code> is, however, a well-known operation. In <a href="https://www.haskell.org">Haskell</a> this is known as a <em>traversal</em>, and it's a completely generic operation: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;Async&lt;&#39;b&gt;)&nbsp;-&gt;&nbsp;&#39;a&nbsp;option&nbsp;-&gt;&nbsp;Async&lt;&#39;b&nbsp;option&gt;</span> <span style="color:blue;">let</span>&nbsp;traverse&nbsp;f&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;x&#39;&nbsp;=&nbsp;f&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;Some&nbsp;x&#39;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;None&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;async&nbsp;{&nbsp;<span style="color:blue;">return</span>&nbsp;None&nbsp;}</pre> </p> <p> You can put this function in a general-purpose module called <code>AsyncOption</code> and cover it by unit tests if you will. You can even put this module in a separate library; it's perfectly decoupled from the the specifics of the registration flow domain. </p> <p> If you do that, <code>completeRegistrationWorkflow</code> doesn't change, but the composition does: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;sut&nbsp;pid&nbsp;r&nbsp;=&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;p&nbsp;=&nbsp;AsyncOption.traverse&nbsp;(twoFA.VerifyProof&nbsp;r.Mobile)&nbsp;pid &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return!</span>&nbsp;completeRegistrationWorkflow &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;twoFA.CreateProof &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;db.CompleteRegistration &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;p &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> You're now back where you'd like to be: One impure action produces a value that you can pass to another function. There's no explicit branching in the code. The cyclomatic complexity remains one. </p> <h3 id="58e1461e9e304afd8c491f94150ebd35"> Change return type <a href="#58e1461e9e304afd8c491f94150ebd35" title="permalink">#</a> </h3> <p> That first refactoring takes care of one out of three impure dependencies. Next, you can get rid of <code>createProof</code>. This one seems to be more difficult to get rid of. It doesn't seem to be required only in the <code>Some</code> case, so a <code>map</code> or <code>traverse</code> can't work. In both cases, however, the result of calling <code>createProof</code> is handled in exactly the same way. </p> <p> Here's another common trick in functional programming: <a href="/2016/09/26/decoupling-decisions-from-effects">Decouple decisions from effects</a>. Return a value that indicates the decision that the function reaches, and then let the second impure action of the impure/pure/impure sandwich act on the decision. </p> <p> In this case, you can model your decision as a <code>Mobile option</code>. You might want to consider a more explicit type, in order to better communicate intent, but it's best to keep each refactoring step small: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;completeRegistrationWorkflow &nbsp;&nbsp;&nbsp;&nbsp;(completeRegistration:&nbsp;Registration&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Async&lt;unit&gt;) &nbsp;&nbsp;&nbsp;&nbsp;(proof:&nbsp;bool&nbsp;option) &nbsp;&nbsp;&nbsp;&nbsp;(registration:&nbsp;Registration) &nbsp;&nbsp;&nbsp;&nbsp;:&nbsp;Async&lt;Mobile&nbsp;option&gt;&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;proof&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;None&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">return</span>&nbsp;Some&nbsp;registration.Mobile &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;isValid&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;isValid&nbsp;<span style="color:blue;">then</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;completeRegistration&nbsp;registration &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;None &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;Some&nbsp;registration.Mobile &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> Notice that the <code>createProof</code> dependency is no longer required. I've removed it from the argument list of <code>completeRegistrationWorkflow</code>. </p> <p> The composition now looks like this: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;createFixture&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;twoFA&nbsp;=&nbsp;Fake2FA&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;db&nbsp;=&nbsp;FakeRegistrationDB&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;sut&nbsp;pid&nbsp;r&nbsp;=&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;p&nbsp;=&nbsp;AsyncOption.traverse&nbsp;(twoFA.VerifyProof&nbsp;r.Mobile)&nbsp;pid &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;res&nbsp;=&nbsp;completeRegistrationWorkflow&nbsp;db.CompleteRegistration&nbsp;p&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;pidr&nbsp;=&nbsp;AsyncOption.traverse&nbsp;twoFA.CreateProof&nbsp;res &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;pidr &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;Option.map&nbsp;ProofRequired &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;Option.defaultValue&nbsp;RegistrationCompleted&nbsp;}</pre> </p> <p> Thanks to the <code>let!</code> binding, the result <code>res</code> is a <code>Mobile option</code>. You can now let the <code>twoFA.CreateProof</code> method <code>traverse</code> over <code>res</code>. This produces an <code>Async&lt;Option&lt;ProofId&gt;&gt;</code> that you can <code>let!</code>-bind to <code>pidr</code> - a <code>ProofId option</code>. </p> <p> You can use <code>Option.map</code> to wrap the <code>ProofId</code> value in a <code>ProofRequired</code> case, if it's there. This step of the final pipeline produces a <code>CompleteRegistrationResult option</code>. </p> <p> Finally, you can use <code>Option.defaultValue</code> to fold the <code>option</code> into a <code>CompleteRegistrationResult</code>. The default value is <code>RegistrationCompleted</code>. This is the case value that'll be used if the <code>option</code> is <code>None</code>. </p> <p> Again, the composition has a cyclomatic complexity of one, and the type of the <code>sut</code> remains <code>ProofId option -&gt; Registration -&gt; Async&lt;CompleteRegistrationResult&gt;</code>. This is a true refactoring. The type of the SUT remains the same, and no behaviour changes. The tests still pass, even though I haven't had to edit them. </p> <h3 id="6550df202542434e85937da702901cd1"> Change return type to Result <a href="#6550df202542434e85937da702901cd1" title="permalink">#</a> </h3> <p> Consider the intent of <code>completeRegistrationWorkflow</code>. The purpose of the operation is to <em>complete</em> a registration workflow. The name is quite explicit. Thus, the <em>happy path</em> is when the proof ID is valid and the function can call <code>completeRegistration</code>. </p> <p> Usually, when you call a function that returns an <code>option</code>, the implied contract is that the <code>Some</code> case represents the happy path. That's not the case here. The <code>Some</code> case carries information about the error paths. This isn't <a href="/2015/08/03/idiomatic-or-idiosyncratic">idiomatic</a>. </p> <p> It'd be more appropriate to use a <code>Result</code> return value: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;completeRegistrationWorkflow &nbsp;&nbsp;&nbsp;&nbsp;(completeRegistration:&nbsp;Registration&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Async&lt;unit&gt;) &nbsp;&nbsp;&nbsp;&nbsp;(proof:&nbsp;bool&nbsp;option) &nbsp;&nbsp;&nbsp;&nbsp;(registration:&nbsp;Registration) &nbsp;&nbsp;&nbsp;&nbsp;:&nbsp;Async&lt;Result&lt;unit,&nbsp;Mobile&gt;&gt;&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;proof&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;None&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">return</span>&nbsp;Error&nbsp;registration.Mobile &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;isValid&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;isValid&nbsp;<span style="color:blue;">then</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">do!</span>&nbsp;completeRegistration&nbsp;registration &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;Ok&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;Error&nbsp;registration.Mobile &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> This change is in itself small, but it does require some changes to the composition. Just as you had to add an <code>Option.traverse</code> function when the return type was an <code>option</code>, you'll now have to add similar functionality to <code>Result</code>. <em>Result</em> is also known as <a href="/2018/06/11/church-encoded-either">Either</a>. Not only <a href="/2019/01/07/either-bifunctor">is it a bifunctor</a>, you can also traverse both axes. Haskell calls this a <code>bitraversable</code> functor. </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;Async&lt;&#39;b&gt;)&nbsp;-&gt;&nbsp;(&#39;c&nbsp;-&gt;&nbsp;Async&lt;&#39;d&gt;)&nbsp;-&gt;&nbsp;Result&lt;&#39;a,&#39;c&gt;&nbsp;-&gt;&nbsp;Async&lt;Result&lt;&#39;b,&#39;d&gt;&gt;</span> <span style="color:blue;">let</span>&nbsp;traverseBoth&nbsp;f&nbsp;g&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Ok&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;x&#39;&nbsp;=&nbsp;f&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;Ok&nbsp;x&#39;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Error&nbsp;e&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;e&#39;&nbsp;=&nbsp;g&nbsp;e &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;Error&nbsp;e&#39;&nbsp;}</pre> </p> <p> Here I just decided to call the function <code>traverseBoth</code> and the module <code>AsyncResult</code>. </p> <p> You're also going to need the equivalent of <code>Option.defaultValue</code> for <code>Result</code>. Something that translates both dimensions of <code>Result</code> into the same type. That's the <a href="/2019/06/03/either-catamorphism">Either catamorphism</a>, so you could, for example, introduce another general-purpose function called <code>cata</code>: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;(&#39;c&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;Result&lt;&#39;a,&#39;c&gt;&nbsp;-&gt;&nbsp;&#39;b</span> <span style="color:blue;">let</span>&nbsp;cata&nbsp;f&nbsp;g&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Ok&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;f&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Error&nbsp;e&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;g&nbsp;e</pre> </p> <p> This is another entirely general-purpose function that you can put in a general-purpose module called <code>Result</code>, in a general-purpose library. You can also cover it by unit tests, if you like. </p> <p> These two general-purpose functions enable you to compose the workflow: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;createFixture&nbsp;()&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;twoFA&nbsp;=&nbsp;Fake2FA&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;db&nbsp;=&nbsp;FakeRegistrationDB&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;sut&nbsp;pid&nbsp;r&nbsp;=&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;p&nbsp;=&nbsp;AsyncOption.traverse&nbsp;(twoFA.VerifyProof&nbsp;r.Mobile)&nbsp;pid &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;res&nbsp;=&nbsp;completeRegistrationWorkflow&nbsp;db.CompleteRegistration&nbsp;p&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;pidr&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;AsyncResult.traverseBoth &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:blue;">fun</span>&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;async&nbsp;{&nbsp;<span style="color:blue;">return</span>&nbsp;()&nbsp;}) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;twoFA.CreateProof &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;res &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;pidr &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;Result.cata&nbsp;(<span style="color:blue;">fun</span>&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;RegistrationCompleted)&nbsp;ProofRequired&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;sut,&nbsp;twoFA,&nbsp;db</pre> </p> <p> This looks more confused than previous iterations. From here, though, it'll get better again. The first two lines of code are the same as before, but now <code>res</code> is a <code>Result&lt;unit, Mobile&gt;</code>. You still need to let <code>twoFA.CreateProof</code> traverse the 'error path', but now you also need to take care of the happy path. </p> <p> In the <code>Ok</code> case you have a <code>unit</code> value (<code>()</code>), but <code>traverseBoth</code> expects its <code>f</code> and <code>g</code> functions to return <code>Async</code> values. I could have fixed that with a more specialised <code>traverseError</code> function, but we'll soon move on from here, so it's hardly worthwhile. </p> <p> In Haskell, you can 'elevate' a value simply with the <code>pure</code> function, but in F#, you need the more cumbersome <code>(fun () -&gt; async { return () })</code> to achieve the same effect. </p> <p> The traversal produces <code>pidr</code> (for <em>Proof ID Result</em>) - a <code>Result&lt;unit, ProofId&gt;</code> value. </p> <p> Finally, it uses <code>Result.cata</code> to turn both the <code>Ok</code> and <code>Error</code> dimensions into a single <code>CompleteRegistrationResult</code> that can be returned. </p> <h3 id="d1c0adc81bc241c7a7a2ea9042356f24"> Removing the last dependency <a href="#d1c0adc81bc241c7a7a2ea9042356f24" title="permalink">#</a> </h3> <p> There's still one dependency left: the <code>completeRegistration</code> function, but it's now trivial to remove. Instead of calling the dependency function from within <code>completeRegistrationWorkflow</code> you can use the same trick as before. Decouple the decision from the effect. </p> <p> Return information about the decision the function made. In the above incarnation of the code, the <code>Ok</code> dimension is currently empty, since it only returns <code>unit</code>. You can use that 'channel' to communicate that you decided to complete a registration: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;completeRegistrationWorkflow &nbsp;&nbsp;&nbsp;&nbsp;(proof:&nbsp;bool&nbsp;option) &nbsp;&nbsp;&nbsp;&nbsp;(registration:&