ploeh blog 2020-03-30T08:05:56+00:00 Mark Seemann danish software design https://blog.ploeh.dk 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> Repeatable execution in C#. </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 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>Repeatable execution in C#</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><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 weakly deterministic, 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> <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 significant whitespace (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> <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 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 use the number as a threshold. 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:&nbsp;Registration) &nbsp;&nbsp;&nbsp;&nbsp;:&nbsp;Async&lt;Result&lt;Registration,&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;">return</span>&nbsp;Ok&nbsp;registration &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 is another small change. When <code>isValid</code> is <code>true</code>, the function no longer calls <code>completeRegistration</code>. Instead, it returns <code>Ok registration</code>. This means that the return type is now <code>Async&lt;Result&lt;Registration, Mobile&gt;&gt;</code>. It also means that you can remove the <code>completeRegistration</code> function argument. </p> <p> In order to compose this variation, you need one new general-purpose function. Perhaps you find this barrage of general-purpose functions exhausting, but it's an artefact of a design philosophy of the F# language. The F# base library contains only few general-purpose functions. Contrast this with <a href="https://en.wikipedia.org/wiki/Glasgow_Haskell_Compiler">GHC</a>'s <a href="http://hackage.haskell.org/package/base">base</a> library, which comes with all of these functions built in. </p> <p> The new function is like <code>Result.cata</code>, but over <code>Async&lt;Result&lt;_&gt;&gt;</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;Async&lt;Result&lt;&#39;a,&#39;c&gt;&gt;&nbsp;-&gt;&nbsp;Async&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;cata&nbsp;f&nbsp;g&nbsp;r&nbsp;=&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;r&#39;&nbsp;=&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;Result.cata&nbsp;f&nbsp;g&nbsp;r&#39;&nbsp;}</pre> </p> <p> Since this function does conceptually the same as <code>Result.cata</code> I decided to retain the name <code>cata</code> and just put it in the <code>AsyncResult</code> module. (This may not be strictly correct, as I haven't really given a lot of thought to what a catamorphism for <code>Async</code> would look like, if one exists. I'm open to suggestions about better naming. After all, <code>cata</code> is hardly an idiomatic F# name.) </p> <p> With <code>AsyncResult.cata</code> you can now compose the system: </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;">let!</span>&nbsp;res&nbsp;=&nbsp;completeRegistrationWorkflow&nbsp;p&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return!</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;res &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 &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> Not only did the call to <code>completeRegistrationWorkflow</code> get even simpler, but you also now avoid the awkwardly named <code>pidr</code> value. Thanks to the <code>let!</code> binding, <code>res</code> has the type <code>Result&lt;Registration, Mobile&gt;</code>. </p> <p> Note that you can now let both impure actions (<code>db.CompleteRegistration</code> and <code>twoFA.CreateProof</code>) traverse the result. This step produces an <code>Async&lt;Result&lt;unit, ProofId&gt;&gt;</code> that's immediately piped to <code>AsyncResult.cata</code>. This reduces the two alternative dimensions of the <code>Result</code> to a single <code>Async&lt;CompleteRegistrationResult&gt;</code> value. </p> <p> The <code>completeRegistrationWorkflow</code> function now begs to be further simplified. </p> <h3 id="db6e044e55f749ba8794d7a8f74e02f4"> Pure registration workflow <a href="#db6e044e55f749ba8794d7a8f74e02f4" title="permalink">#</a> </h3> <p> <a href="/2019/02/11/asynchronous-injection">Once you remove all dependencies, your domain logic doesn't have to be asynchronous</a>. Nothing asynchronous happens in <code>completeRegistrationWorkflow</code>, so simplify it: </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:&nbsp;Registration) &nbsp;&nbsp;&nbsp;&nbsp;:&nbsp;Result&lt;Registration,&nbsp;Mobile&gt;&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;None&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Error&nbsp;registration.Mobile &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;isValid&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;isValid&nbsp;<span style="color:blue;">then</span>&nbsp;Ok&nbsp;registration &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;Error&nbsp;registration.Mobile</pre> </p> <p> Gone is the <code>async</code> computation expression, including the <code>return</code> keyword. This is now a <a href="https://en.wikipedia.org/wiki/Pure_function">pure function</a>. </p> <p> You'll have to adjust the composition once more, but it's only a minor change: </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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;completeRegistrationWorkflow&nbsp;p&nbsp;r &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 &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> The result of invoking <code>completeRegistrationWorkflow</code> is no longer an <code>Async</code> value, so there's no reason to <code>let!</code>-bind it. Instead, you can call it and immediately pipe its output to <code>AsyncResult.traverseBoth</code>. </p> <h3 id="9a4c3af0f30843c2816af97a08b2f99b"> DRY <a href="#9a4c3af0f30843c2816af97a08b2f99b" title="permalink">#</a> </h3> <p> Consider <code>completeRegistrationWorkflow</code>. Can you make it simpler? </p> <p> At this point it should be evident that two of the branches contain duplicate code. Applying the <a href="https://en.wikipedia.org/wiki/Don%27t_repeat_yourself">DRY principle</a> you can simplify it: </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:&nbsp;Registration) &nbsp;&nbsp;&nbsp;&nbsp;:&nbsp;Result&lt;Registration,&nbsp;Mobile&gt;&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;Some&nbsp;<span style="color:blue;">true</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Ok&nbsp;registration &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Error&nbsp;registration.Mobile</pre> </p> <p> I'm not too fond of this style of type annotation for simple functions like this, so I'd like to remove it: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;completeRegistrationWorkflow&nbsp;proof&nbsp;registration&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;Some&nbsp;<span style="color:blue;">true</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Ok&nbsp;registration &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Error&nbsp;registration.Mobile</pre> </p> <p> These two steps are pure refactorings: they only reorganise the code that implements <code>completeRegistrationWorkflow</code>, so the composition doesn't change. </p> <h3 id="705c34900d6342f3a79356734a67b355"> Essential complexity <a href="#705c34900d6342f3a79356734a67b355" title="permalink">#</a> </h3> <p> While reading this article, you may have felt frustration gather. <em>This is cheating! You took out all of the complexity. Now there's nothing left!</em> You're likely to feel that I've moved a lot of behaviour into untestable code. I've done nothing of the sort. </p> <p> I'll remind you that while functions like <code>AsyncOption.traverse</code> and <code>AsyncResult.cata</code> do contain branching behaviour, they <em>can</em> be tested. In fact, <a href="/2015/05/07/functional-design-is-intrinsically-testable">since they're pure functions, they're intrinsically testable</a>. </p> <p> It's true that a <em>composition</em> of a pure function with its impure dependencies may not be (unit) testable, but that's also true for a Dependency Injection-based object graph composed in a Composition Root. </p> <p> Compositions of functions may look non-trivial, but to a degree, the type system will assist you. If your composition compiles, it's likely that you've composed the impure/pure/impure sandwich correctly. </p> <p> Did I take out all the complexity? I didn't. There's a bit left; the function now has a cyclomatic complexity of <em>two</em>. If you look at the original function, you'll see that <em>the duplication was there all along</em>. Once you remove all the accidental complexity, you uncover the essential complexity. This happens to me so often when I apply functional programming principles that <a href="/2019/07/01/yes-silver-bullet">I fancy that functional programming is a silver bullet</a>. </p> <h3 id="0086592a037947e397169271eeaad627"> Pipeline composition <a href="#0086592a037947e397169271eeaad627" title="permalink">#</a> </h3> <p> We're mostly done now. The problem now appears in all its simplicity, and you have an impure/pure/impure sandwich. </p> <p> You can still improve the code, though. </p> <p> If you consider the current composition, you may find that <code>p</code> isn't the best variable name. I admit that I struggled with naming that variable. <a href="/2016/10/25/when-variable-names-are-in-the-way">Sometimes, variable names are in the way</a> and the code might be clearer if you could elide them by composing a pipeline of functions. </p> <p> That's always worth an attempt. This time, ultimately I find that it doesn't improve things, but even an attempt can be illustrative. </p> <p> If you want to eliminate a named value, you can often do so by piping the output of the function that produced the variable directly to the next function. This does, however, require that the function argument is the right-most. Currently, that's not the case. <code>registration</code> is right-most, and <code>proof</code> is to the left. </p> <p> There's no compelling reason that the arguments should come in that order, so flip them: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;completeRegistrationWorkflow&nbsp;registration&nbsp;proof&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;Some&nbsp;<span style="color:blue;">true</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Ok&nbsp;registration &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Error&nbsp;registration.Mobile</pre> </p> <p> This enables you to write the entire composition as a single pipeline: </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;">return!</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;AsyncOption.traverse&nbsp;(twoFA.VerifyProof&nbsp;r.Mobile)&nbsp;pid &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;Async.map&nbsp;(completeRegistrationWorkflow&nbsp;r) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;Async.bind&nbsp;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;AsyncResult.traverseBoth&nbsp;db.CompleteRegistration&nbsp;twoFA.CreateProof &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&gt;&gt;&nbsp;AsyncResult.cata&nbsp;(<span style="color:blue;">fun</span>&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;RegistrationCompleted)&nbsp;ProofRequired) &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> This does, however, call for two new general-purpose functions: <code>Async.map</code> and <code>Async.bind</code>: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;Async&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;Async&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;map&nbsp;f&nbsp;x&nbsp;=&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;x&#39;&nbsp;=&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;f&nbsp;x&#39;&nbsp;} <span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;Async&lt;&#39;b&gt;)&nbsp;-&gt;&nbsp;Async&lt;&#39;a&gt;&nbsp;-&gt;&nbsp;Async&lt;&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;bind&nbsp;f&nbsp;x&nbsp;=&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;x&#39;&nbsp;=&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return!</span>&nbsp;f&nbsp;x&#39;&nbsp;}</pre> </p> <p> In my opinion, these functions ought to belong to F#'s <code>Async</code> module, but for <a href="https://github.com/fsharp/fslang-suggestions/issues/318">for reasons that aren't clear to me, they don't</a>. As you can see, though, they're easy to add. </p> <p> While the this change gets rid of the <code>p</code> variable, I don't think it makes the overall composition easier to understand. The action of swapping the function arguments does, however, enable another simplification. </p> <h3 id="db99963569414669a865d4d10ad95b6e"> Eta reduction <a href="#db99963569414669a865d4d10ad95b6e" title="permalink">#</a> </h3> <p> Now that <code>proof</code> is <code>completeRegistrationWorkflow</code>'s last function argument, you can perform an <em>eta reduction:</em> </p> <p> <pre><span style="color:blue;">let</span>&nbsp;completeRegistrationWorkflow&nbsp;registration&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;<span style="color:blue;">true</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Ok&nbsp;registration &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Error&nbsp;registration.Mobile</pre> </p> <p> Not everyone is a fan of the <a href="https://en.wikipedia.org/wiki/Tacit_programming">point-free style</a>, but I like it. YMMV. </p> <h3 id="798d1bb566224090a676d386afc54ea4"> Sandwich <a href="#798d1bb566224090a676d386afc54ea4" title="permalink">#</a> </h3> <p> Regardless of whether you prefer <code>completeRegistrationWorkflow</code> in point-free or pointed style, I think that the composition needs improvement. It should explicitly communicate that it's an impure/pure/impure sandwich. This makes it necessary to reintroduce some variables, so I'm also going to bite the bullet and devise some better names. </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;validityOfProof&nbsp;=&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;AsyncOption.traverse&nbsp;(twoFA.VerifyProof&nbsp;r.Mobile)&nbsp;pid &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;decision&nbsp;=&nbsp;completeRegistrationWorkflow&nbsp;r&nbsp;validityOfProof &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 &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> Instead of <code>p</code>, I decided to call the first value <code>validityOfProof</code>. This is the result of the first impure action in the sandwich (the upper slice of bread). </p> <p> While <code>validityOfProof</code> is the result of an impure action, the value itself is pure and can be used as input to <code>completeRegistrationWorkflow</code>. This is the pure part of the sandwich. I called the output <code>decision</code> because the workflow makes a decision based on its input, and it's up to the caller to act on that decision. </p> <p> Notice that <code>decision</code> is bound with a <code>let</code> binding (instead of a <code>let!</code> binding), despite taking place inside an <code>async</code> workflow. This is because <code>completeRegistrationWorkflow</code> is pure. It doesn't return an <code>Async</code> value. </p> <p> The second impure action acts on <code>decision</code> through a pipeline of <code>AsyncResult.traverseBoth</code> and <code>AsyncResult.cata</code>, as previously explained. </p> <p> I think that the impure/pure/impure sandwich is more visible like this, so that was my final edit. I'm happy with how it looks now. </p> <h3 id="a4c98d81322e4010a0dfcb1c59955812"> Conclusion <a href="#a4c98d81322e4010a0dfcb1c59955812" title="permalink">#</a> </h3> <p> I don't claim that you can always refactor code to an impure/pure/impure sandwich. In fact, <a href="/2017/07/10/pure-interactions">I can easily envision categories of software where such an architecture seems impossible</a>. </p> <p> Still, I find it intriguing that when I find myself in the realm of web services or message-based applications, I can't recall a case where a sandwich has been impossible. Surely, there must cases where it is so. That's the reason that I solicit examples. This article was a response to such an example. I found it fruitful, because it enabled me to discuss several useful techniques for composing behaviour in a functional architecture. On the other hand, it failed to be a counter-example. </p> <p> I'm sure that some readers are left with a nagging doubt. <em>That's all very impressive, but would you actually write code like that in a piece of production software?</em> </p> <p> If it was up to me, then: <em>yes.</em> I find that when I can keep code pure, it's trivial to unit test and there's no test-induced damage. Functions also compose in a way objects don't easily do, so there's many advantages to functional programming. I'll take them when they're available. </p> <p> As always, context matters. I've been in team settings where other team members would embrace this style of programming, and in other environments where team members wouldn't understand what was going on. In the latter case, I'd adjust my approach to challenge, not alienate, other team members. </p> <p> My intention with this article was to show what's <em>possible</em>, not to dictate what you should do. That's up to you. </p> <p> This article is the December 2 entry in the <a href="https://sergeytihon.com/2019/11/05/f-advent-calendar-in-english-2019">F# Advent Calendar in English 2019</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header">Comments</h2> <div class="comment" id="7c05edb624b54cafacc204e60b42bbf3"> <div class="comment-author"><a href="https://www.relativisticramblings.com/">Christer van der Meeren</a></div> <div class="comment-content"> <p>Thank you so much for the comprehensive reply to my comment. It was very instructive to see refactoring process, from thought to code. The post is an excellent reply to the question I asked.</p> <h3>A slight modification</h3> <p>In my original comment, I made one simplification that, in hindsight, I perhaps should not have made. It is not critical, but it complicates things slightly. In reality, the <code>completeRegistration</code> function does not return <code>Async&lt;unit&gt;</code>, but <code>Async&lt;Result&lt;unit, CompleteRegistrationError&gt;&gt;</code> (where, currently, <code>CompleteRegistrationError</code> has the single case <code>UserExists</code>, returned if the DB throws a unique constraint error).</p> <p>As I see it, the impact of this to your refactoring is two-fold:</p> <ul> <li>You can&#39;t easily use <code>AsyncResult.traverseBoth</code>, since the signatures between the two cases aren&#39;t compatible (unless you want to mess around with nested <code>Result</code> values). You could write a custom <code>traverse</code> function just for the needed signature, but then we’ve traveled well into the lands of “generic does not imply general”.</li> <li>It might be better to model the registration result (completed vs. proof required) as its own DU, with <code>Result</code> being reserved for actual errors.</li> </ul> <h3>Evaluating the refactoring</h3> <p>My original comment ended in the following question (emphasis added):</p> <blockquote><p>Is it possible to refactor this to direct input/output, <strong>in a way that actually reduces complexity where it matters?</strong></p> </blockquote> <p>With this (vague) question and the above modifications in mind, let&#39;s look at the relevant code before/after. In both cases, there are two functions: The workflow/logic, and the composition.</p> <h4>Before</h4> <p>Before refactoring, we have a slightly complex impure workflow (which still is fairly easily testable using state-based testing, as you so aptly demonstrated) – note the <code>asyncResult</code> CE (I’m using the excellent FsToolkit.ErrorHandling, if anyone wonders) and the updated signatures; otherwise it’s the same:</p> <pre><code class='language-f#' lang='f#'>let completeRegistrationWorkflow (createProof: Mobile -&gt; Async&lt;ProofId&gt;) (verifyProof: Mobile -&gt; ProofId -&gt; Async&lt;bool&gt;) (completeRegistration: Registration -&gt; Async&lt;Result&lt;unit, CompleteRegistrationError&gt;&gt;) (proofId: ProofId option) (registration: Registration) : Async&lt;Result&lt;CompleteRegistrationResult, CompleteRegistrationError&gt;&gt; = asyncResult { match proofId with | None -&gt; let! proofId = createProof registration.Mobile return ProofRequired proofId | Some proofId -&gt; let! isValid = verifyProof registration.Mobile proofId if isValid then do! completeRegistration registration return RegistrationCompleted else let! proofId = createProof registration.Mobile return ProofRequired proofId } </code></pre> <p>Secondly, we have the trivial &quot;humble object&quot; composition, which looks like this:</p> <pre><code class='language-f#' lang='f#'>let complete proofId validReg = Workflows.Registration.complete Http.createMobileClaimProof Http.verifyMobileClaimProof Db.completeRegistration proofId validReg </code></pre> <p>The composition is, indeed, humble – the only thing it does is call the higher-order workflow function with the correct parameters. It has no cyclomatic complexity and is trivial to read, and I don&#39;t think anyone would consider it necessary to test.</p> <h4>After</h4> <p>After refactoring, we have the almost trivial pure function we extracted (for simplicity I let it return <code>Result</code> here, as you proposed):</p> <pre><code class='language-f#' lang='f#'>let completePure reg proofValidity = match proofValidity with | Some true -&gt; Ok reg | Some false | None -&gt; Error reg.Mobile </code></pre> <p>Secondly, we have the composition function. Now, with the modification to <code>completeRegistration</code> (returning <code>Async&lt;Result&lt;_,_&gt;&gt;</code>), it can&#39;t as easily be written in point-free style. You might certainly be able to improve it, but here is my quick initial take.</p> <pre><code class='language-f#' lang='f#'>let complete proofId reg : Async&lt;Result&lt;CompleteRegistrationResult, CompleteRegistrationError&gt;&gt; = asyncResult { let! proofValidity = proofId |&gt; Option.traverseAsync (Http.verifyMobileClaimProof reg.Mobile) match completePure reg proofValidity with | Ok reg -&gt; do! Db.completeRegistration reg return RegistrationCompleted | Error mobile -&gt; let! proofId = Http.createMobileClaimProof mobile return ProofRequired proofId } </code></pre> <h4>Evaluation</h4> <p>Now that we have presented the code before/after, let us take stock of what we have gained and lost by the refactoring.</p> <p>Pros:</p> <ul> <li>We have gotten rid of the &quot;DI workflow&quot; entirely</li> <li>More of the logic is pure</li> </ul> <p>Cons:</p> <ul> <li>The logic we extracted to a pure function is almost trivial. This is not in itself bad, but one can wonder whether it was worth it (apart from the purely instructive aspects).</li> <li>If the extracted logic is pure, where then did the rest of the complexity go? The only place it could – it ended up in the &quot;composition&quot;, i.e. the &quot;humble object&quot;. The composition function isn&#39;t just calling a higher-order function with the correct function arguments any more; it has higher cyclomatic complexity and is much harder to read, and can&#39;t be easily tested (since it&#39;s a composition function). The new composition is, so to say, quite a bit less humble than the original composition. This is particularly evident in my updated version, but personally I also have to look at your simpler(?), point-free version a couple of times to convince myself that it is, really, not doing anything wrong. (Though regardless of whether a function is written point-free or not, it does the exact same thing and has the same complexity.)</li> <li>To the point above: The composition function needs many &quot;complex&quot; helper functions that would likely confuse, if not outright alienate beginner F# devs (which could, for example, lead to worse onboarding). This is particularly relevant for non-standard functions like <code>AsyncOption.traverse</code>, <code>AsyncResult.traverseBoth</code>, <code>AsyncResult.cata</code>, etc.</li> </ul> <p>Returning to my initial question: Does the refactoring “reduce complexity where it matters?“ I’m not sure. This is (at least partly) “personal opinions” territory, of course, and my vague question doesn’t help. But personally I find the result of the refactoring more complex to understand than the original, DI workflow-based version.</p> <p>Based on Scott Wlaschin’s book Domain Modelling Made Functional, it’s possible he might agree. He seems very fond of the “DI workflow” approach there. I personally prefer a bit more dependency rejection than that, because I find “DR”/sandwiches often leads to simpler code, but in this particular case, I may prefer the impure DI workflow, tested using state-based testing. At least for the more complex code I described, but perhaps also for your original example.</p> <p>Still, I truly appreciate your taking the time to respond in this manner. It was very instructive, as always, which was after all the point. And you’re welcome to share any insights regarding this comment, too.</p> </div> <div class="comment-date">2019-12-03 13:46 UTC</div> </div> <div class="comment" id="e90332adb7d24e2b8aa1484c302b6f8c"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Christer, thank you for writing. This is great! One of your comments inspires me to compose another article that I've long wanted to write. If I manage to produce it in time, I'll publish it Monday. Once that's done, I'll respond here in a more thorough manner. </p> <p> When I do that, however, I don't plan to reproduce your updated example, or address it in detail. I see nothing in it that invalidates what I've already written. As far as I can tell, you don't need to explicitly pattern-match on <code>completePure reg proofValidity</code>. You should be able to map or traverse over it like already shown. If you want my help with the details, I'll be happy to do so, but then please prepare a <a href="https://en.wikipedia.org/wiki/Minimal_working_example">minimal working example</a> like I did for this article. You can either fork <a href="https://github.com/ploeh/RegistrationFlow">my example</a> or make a new repository. </p> </div> <div class="comment-date">2019-12-04 8:35 UTC</div> </div> <div class="comment" id="785e708f61b14ad0825d1359cbebd8a2"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> This is a fantastic post Mark! Thank you very much for going step-by-step while explaining how you refactored this code. </p> <blockquote> I find it intriguing that when I find myself in the realm of web services or message-based applications, I can't recall a case where a [impure/pure/impure] sandwich has been impossible. Surely, there must cases where it is so. That's the reason that I solicit examples. </blockquote> <p> I would like to suggest a example in the realm of web services or message-based applications that cannot be expressed as a impure/pure/impure sandwich. </p> <p> Let's call an "impure/pure/impure sandwich" an impure-pure-impure composition. More generally, any impure funciton can be expressed as a composition of the form <code>[pure-]impure(-pure-impure)*[-pure]</code>. That is, (1) it might begin with a pure step, then (2) there is an impure step, then (3) there is a sequence of length zero or more containing a pure step followed by an impure step, and lastly (4) it might end with another pure step. One reason an impure fucntion might intentially be expressed by a composition that ends with a pure step is to erase senitive informaiton form the memory hierarchy. For simplicity though, let's assume that any impure function can be refactored so that the corresponding composition ends with an impure step. Let the length of a composition be one plus the number of dashes (<code>-</code>) that it contains. </p> <p> Suppose <code>f</code> is a function with an impure-pure-impure composition such that <code>f</code> cannot be refactored to a fucntion with a composition of a smaller length. Then there exists fucntion <code>f'</code> with a pure-impure-pure-impure composition. The construction uses public-key cryptography. I think this is a natural and practical example. </p> <p> Here is the definition of <code>f'</code> in words. The user sends to the server ciphertext encryped using the server's public key. The user's request is received by a process that already has the server's private key loaded into memory. This process decrypts the user's ciphertext using its private key to obtain some plantext <code>p</code>. This step is pure. Then the process passes <code>p</code> into <code>f</code>. </p> <p> Using symmetric-key cryptography, it is possible to construct a function with a composition of an arbitrarily high length. The following construction reminds me of how <a href="https://en.wikipedia.org/wiki/Onion_routing">union routing</a> works (though each decryption in that case is intended to happen in a different process on a different server). I admit that this example is not very natural or practical. </p> <p> Suppose <code>f</code> is a function with a composition of length <code>n</code>. Then there exists fucntion <code>f'</code> with a composition of length greater than <code>n</code>. Specifically, if the original composition starts with a pure step, then the length is larger by one; if the original composition starts with an impure step, then the length is larger by two. </p> <p> Here is the definition of <code>f'</code> in words. The user sends to the server an ID and ciphertext encryped using a symmetric key that corresponds to the ID. The user's request is received by a process that does not have any keys loaded into memory. First, this process obtains from disk the appropriate symmetric key using the ID. This step is impure. Then this process decrypts the user's ciphertext using this key to obtain some plantext <code>p</code>. This step is pure. Then the process passes <code>p</code> into <code>f</code>. </p> </div> <div class="comment-date">2019-12-06 17:21 UTC</div> </div> <div class="comment" id="0ae83af0cc824c848e5988eb2fb35356"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for writing. Unfortunately, I don't follow your chain of reasoning. Cryptography strikes me as fitting the impure/pure/impure sandwich architecture quite well. There's definitely an initial impure step because you have to initialise a random number generator, as well as load keys, salts, and whatnot from storage. From there, though, the cryptographic algorithms are, as far as I'm aware, pure calculation. I don't see how asymmetric cryptography changes that. </p> <p> The reason that I'm soliciting examples that defy the impure/pure/impure sandwich architecture, however, is that I'm looking for a compelling example. What to do when the sandwich architecture is impossible is a frequently asked question. To be clear, I know what to do in that situation, but I'd like to write an article that answers the question in a compelling way. For that, I need an example that an uninitiated reader can follow. </p> </div> <div class="comment-date">2019-12-07 10:24 UTC</div> </div> <div class="comment" id="e53d31d11b814bccac392dfc0bc03230"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> Sorry that my explanation was unclear. I should have included an example. </p> <blockquote> Cryptography strikes me as fitting the impure/pure/impure sandwich architecture quite well. There's definitely an initial impure step because you have to initialise a random number generator, as well as load keys, salts, and whatnot from storage. From there, though, the cryptographic algorithms are, as far as I'm aware, pure calculation. I don't see how asymmetric cryptography changes that. </blockquote> <p> I agree that cyptographic algorithms are pure. From your qoute that I included above, I get the impression that you have neglected to consider what computation is to be done with the output of the cyptogrpahic algorithm. </p> <p> Here is a specific example of my first construction, which uses public-key cyptography. Consider the function <code>sut</code> that concluded your post. I repeat it for clarity. </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;validityOfProof&nbsp;=&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;AsyncOption.traverse&nbsp;(twoFA.VerifyProof&nbsp;r.Mobile)&nbsp;pid &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;decision&nbsp;=&nbsp;completeRegistrationWorkflow&nbsp;r&nbsp;validityOfProof &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 &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> Let <code>sut</code> be the function <code>f</code> in that construction. In particular, <code>sut</code> is an impure/pure/impure sandwich, or equivalently an impure-pure-impure composition that of course has length 3. Furthermore, I think it is clear that this behavior cannot be expressed as a pure-impure-pure composition, a pure-impure composition, an impure-pure composition, or an impure composition. You worked very hard to simplfy that code, and I believe an implicit claim of yours is that it cannot be simplified any further. </p> <p> In this case, <code>f'</code> would be the following function. </p> <p><pre><span style="color:blue;">let</span>&nbsp;privateKey&nbsp;=&nbsp;... <span style="color:blue;">let</span>&nbsp;sut'&nbsp;ciphertext&nbsp;=&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;(pid,&nbsp;r)&nbsp;=&nbsp;decrypt&nbsp;privateKey&nbsp;ciphertext &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;validityOfProof&nbsp;=&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;AsyncOption.traverse&nbsp;(twoFA.VerifyProof&nbsp;r.Mobile)&nbsp;pid &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;decision&nbsp;=&nbsp;completeRegistrationWorkflow&nbsp;r&nbsp;validityOfProof &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 &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> As I defined it, this function is a pure-impure-pure-impure composition, which has length 4. Maybe in your jargon you would call this a pure/impure/pure/impure sandwich. My claim is that this function cannot be refactored into an impure/pure/impure sandwich. </p> <p> Do you think that my claim is correct? </p> </div> <div class="comment-date">2019-12-07 14:48 UTC</div> </div> <div class="comment" id="189069ae41704900b56403288656a8fe"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for your patience with me. Now I get it. As stated, your composition looks like a pure-impure-pure-impure composition, but unless you hard-code <code>privateKey</code>, you'll have to load that value, which is an impure operation. That would make it an impure-pure-impure-pure-impure composition. </p> <p> The decryption step itself is an impure-pure composition, assuming that we need to load keys, salts, etc. from persistent storage. You might also want to think of it as a 'mostly' pure function, since you could probably load decryption keys once when the application process starts, and keep them around for its entire lifetime. </p> <p> It's a correct example of a more involved interaction model. Thank you for supplying it. Unfortunately, it's not one I can use for an article. Like other cross-cutting concerns like caching, logging, retry mechanisms, etcetera, security can be abstracted away as middleware. This implies that you'd have a middleware action that's implemented as an impure-pure-impure sandwich, and an application feature that's implemented as another impure-pure-impure sandwich. These two sandwiches are unrelated. A change to one of them is unlikely to trigger a change in the other. Thus, we can still base our application architecture on the notion of the impure-pure-impure sandwich. </p> <p> I hope I've explained my demurral in a sensible way. </p> </div> <div class="comment-date">2019-12-08 13:24 UTC</div> </div> <div class="comment" id="c7b6630ebec24c0fad9b5821a0802878"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> This implies that you'd have a middleware action that's implemented as an impure-pure-impure sandwich, and an application feature that's implemented as another impure-pure-impure sandwich. These two sandwiches are unrelated. A change to one of them is unlikely to trigger a change in the other. </blockquote> <p> The are unrelated semantically. Syntatically, the whole application sandwich is the last piece of impure bread on the middleware sandwich. This reminds me of a thought I have had and also heard recently, which is that the structure of code is like a fractal. </p> <p> Anyway, I am hearing you say that you want functions to have "one responsibility", to do "one thing", to change for "one reason". With that constraint satisfied, you are requesting an example of a funciton that is not an impure/pure/impure sandwich. I am up to that challenge. Here is another attempt. </p> <p> Suppose our job is to implement a <a href="https://en.wikipedia.org/wiki/Man-in-the-middle_attack">man-in-the-middle attack</a> in the style of <a href="https://www.schneier.com/blog/archives/2011/06/man-in-the-midd_3.html">Schneier's Chess Grandmaster Problem</a> in which Alice and Bob know that they are communicating with Malory while Malory simply repeats what she hears to the other person. Specifically, Alice is a client and Bob is a server. Mailory acts like a server to Alice and like a client to Bob. The funciton would look something like this. </p> <p><pre><span style="color:blue;">let</span>&nbsp;malroyInTheMiddle&nbsp;aliceToMalory&nbsp;=&nbsp;async&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;maloryToBob&nbsp;=&nbsp;convertIncoming&nbsp;aliceToMalory &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;bobToMalory&nbsp;=&nbsp;service&nbsp;maloryToBob &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;maloryToAlice&nbsp;=&nbsp;convertOutgoing&nbsp;bobToMalory &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;maloryToAlice }</pre></p> <p> This is a pure-impure-pure composition, which is different from an impure-pure-impure composition. </p> </div> <div class="comment-date">2019-12-09 14:28 UTC</div> </div> <div class="comment" id="f2db5259c16e4241b53934ae4dcb17a0"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for writing. The way I understand it, we are to assume that both <code>convertIncoming</code> and <code>convertOutgoing</code> are complicated functions that require substantial testing to get right. Under that assumption, I think that you're right. This doesn't directly fit the impure-pure-impure sandwich architecture. </p> <p> It does, however, fit a simple function composition. As far as I can see, it's equivalent to something like this: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;malroyInTheMiddle&nbsp;&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;Async.fromResult &nbsp;&nbsp;&nbsp;&nbsp;&gt;&gt;&nbsp;Async.map&nbsp;convertIncoming &nbsp;&nbsp;&nbsp;&nbsp;&gt;&gt;&nbsp;Async.bind&nbsp;service &nbsp;&nbsp;&nbsp;&nbsp;&gt;&gt;&nbsp;Async.map&nbsp;convertOutgoing</pre> </p> <p> I haven't tested it, but I'd imagine it to be something like that. </p> <p> To nitpick, this isn't a pure-impure-pure composition, but rather an impure-pure-impure-pure-impure composition. The entry point of a system is always impure, as is the output. </p> </div> <div class="comment-date">2019-12-10 11:29 UTC</div> </div> <div class="comment" id="fea1498fe43543f29a01eb6101dbdb9f"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Christer, I'd hoped that I'd already addressed some of your concerns in the article itself, but I may not have done a good enough job of it. Overall, given a question like <blockquote> "Is it possible to refactor this to direct input/output, in a way that actually reduces complexity where it matters?" </blockquote> I tend to put emphasis on <em>is it possible</em>. Not that the rest of the question is unimportant, but it's more subjective. Perhaps you find that my article didn't answer your question, but I hope at least that I managed to establish that, yes, it's possible to refactor to an impure-pure-impure sandwich. </p> <p> Does it matter? I think it does, but that's subjective. I do think, though, that I can objectively say that <a href="/2018/11/19/functional-architecture-a-definition">my refactoring is functional</a>, whereas <a href="/2017/01/30/partial-application-is-dependency-injection">passing impure functions as arguments isn't</a>. Whether or not an architecture ought to be functional is, again, subjective. No-one says that it has to be. That's up to you. </p> <p> As I wrote in <a href="#e90332adb7d24e2b8aa1484c302b6f8c">my preliminary response</a>, I'm not going to address your modification. I don't see that it matters. Even when you return an <code>Async&lt;Result&lt;_,_&gt;&gt;</code> you can <code>map</code>, <code>bind</code>, or <code>traverse</code> over it. You may not be able to use <code>AsyncResult.traverseBoth</code>, but you can derive specialisations like <code>AsyncResult.traverseOk</code> and <code>AsyncResult.traverseError</code>. </p> <p> First, like you did, I find it illustrative to juxtapose the alternatives. I'm going to use the original example first: </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;} <span style="color:blue;">let</span>&nbsp;sut&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;completeRegistrationWorkflow &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;twoFA.CreateProof &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;twoFA.VerifyProof &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;db.CompleteRegistration</pre> </p> <p> In contrast, here's my refactoring: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;completeRegistrationWorkflow&nbsp;registration&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Some&nbsp;<span style="color:blue;">true</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Ok&nbsp;registration &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Error&nbsp;registration.Mobile <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;validityOfProof&nbsp;=&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;AsyncOption.traverse&nbsp;(twoFA.VerifyProof&nbsp;r.Mobile)&nbsp;pid &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;decision&nbsp;=&nbsp;completeRegistrationWorkflow&nbsp;r&nbsp;validityOfProof &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 &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> It's true that my composition (<code>sut</code>) seems more involved than yours, but the overall trade-off looks good to me. In total, the code is simpler. </p> <p> In your <em>evaluation</em>, you make some claims that I'd like to specifically address. Most are reasonable, but I think a few require special attention: <blockquote> "The logic we extracted to a pure function is almost trivial." </blockquote> Indeed. This should be listed as a <em>pro</em>, not a <em>con</em>. Whether or not it's worth it is a different discussion. </p> <p> As I wrote in the article: <blockquote> "If you look at the original function, you'll see that <em>the duplication was there all along</em>. Once you remove all the accidental complexity, you uncover the essential complexity." </blockquote> (Emphasis from the original.) Isn't it always worth it to take away accidental complexity? <blockquote> "The composition function isn't just calling a higher-order function with the correct function arguments any more; it has higher cyclomatic complexity" </blockquote> <a href="/2019/12/09/put-cyclomatic-complexity-to-good-use/#de927bfcc95d410bbfcd0adf7a63926b">No, it doesn't</a>. It has a cyclomatic complexity of <em>1</em>, exactly like the original humble object. <blockquote> "can't be easily tested" </blockquote> True, but neither can the original humble object. <blockquote> "The new composition is, so to say, quite a bit less humble than the original composition." </blockquote> According to which criterion? It has the same cyclomatic complexity, but I admit that more characters went into typing it. On the other hand, the composition juxtaposed with the actual function has far fewer characters than the original example. </p> <p> You also write that <blockquote> "The composition function needs many "complex" helper functions [...]. This is particularly relevant for non-standard functions like <code>AsyncOption.traverse</code>, <code>AsyncResult.traverseBoth</code>, <code>AsyncResult.cata</code>, etc." </blockquote> I don't like the epithet <em>non-standard</em>. It's true that these functions aren't in <code>FSharp.Core</code>, for reasons that aren't clear to me. In comparison, they're part of the standard <code>base</code> library in Haskell. </p> <p> There's nothing non-standard about functions like these. Like <code>map</code> and <code>bind</code>, traversals and catamorphisms are <a href="/2017/10/04/from-design-patterns-to-category-theory">universal abstractions</a>. They exist independently of particular programming languages or library packages. </p> <p> I think that it's fair criticism that they may not be friendly to absolute beginners, but they're still fairly basic ideas that address real needs. The same can be said for the <code>asyncResult</code> computation expression that you've decided to use. It's also 'non-standard' only in the sense that it's not part of <code>FSharp.Core</code>, but otherwise standard in that it's just a stack of monads, and plenty of libraries supply that functionality. You can also write that computation expression yourself in a dozen lines of code. </p> <p> In the end, all of this is subjective. As I also wrote in my conclusion: <blockquote> <p> "I've been in team settings where [...] team members wouldn't understand what was going on. In the latter case, I'd adjust my approach to challenge, not alienate, other team members. </p> <p> "My intention with this article was to show what's possible, not to dictate what you should do." </p> </blockquote> What I do, however, think is important to realise is that what I suggest is to learn a set of concepts <em>once</em>. Once you understand <a href="/2018/03/22/functors">functors</a>, monads, traversals etcetera, that's knowledge that applies to F#, Haskell, C#, JavaScript (I suppose) and so on. </p> <p> Personally, I find it a better investment of my time to learn a general concept once, and then work with trivial code, rather than having to learn, over and over again, how to deal with each new code base's accidental complexity. </p> </div> <div class="comment-date">2019-12-12 2:56 UTC</div> </div> <div class="comment" id="e0c12e5a6148400aac256cf3b800ff4f"> <div class="comment-author"><a href="https://www.relativisticramblings.com/">Christer van der Meeren</a></div> <div class="comment-content"> <p>Mark, thank you for getting back to me with a detailed response.</p> <p>First, a general remark. I see that my comment might have been a bit &quot;sharp around the edges” and phrased somewhat carelessly, giving the impression that I was not happy with your treatment of my example. I’d just like to clearly state that I am. You replied in your usual clear manner to exactly the question I posed, and seeing your process and solution was instructive for me.</p> <p>We are all learning, all the time, and if I use a strong voice, that is primarily because <a href='https://blog.codinghorror.com/strong-opinions-weakly-held/'>strong opinions, weakly held</a> often seems to be a fruitful way to drive discussion and learning.</p> <p>With that in mind, allow me to address some of your remarks and possibly soften my previous comment.</p> <blockquote><p>Perhaps you find that my article didn&#39;t answer your question, but I hope at least that I managed to establish that, yes, it&#39;s possible to refactor to an impure-pure-impure sandwich.</p> </blockquote> <p>Your article did indeed answer my question. My takeaway (then, not necessarily now after reading the rest of your comment) was that you managed to refactor to impure-pure-impure at the &quot;expense” of making the non-pure part harder to understand. But as you say, that’s subjective, and your remarks on that later in your comment was a good point of reflection for me. I’ll get to that later.</p> <blockquote><p>Does it matter? I think it does, but that&#39;s subjective. I do think, though, that I can objectively say that <a href='https://blog.ploeh.dk/2018/11/19/functional-architecture-a-definition'>my refactoring is functional</a>, whereas <a href='https://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection'>passing impure functions as arguments isn&#39;t</a>. Whether or not an architecture ought to be functional is, again, subjective. No-one says that it has to be. That&#39;s up to you.</p> </blockquote> <p>I agree on all points.</p> <blockquote><p>First, like you did, I find it illustrative to juxtapose the alternatives.</p> </blockquote> <p>I don’t agree 100% that it’s a completely fair comparison, since you’re leaving out the implementations of <code>AsyncOption.traverse</code>, <code>AsyncResult.traverseBoth</code>, and <code>AsyncResult.cata</code>. However, I get why you are doing it. These are generic utility functions for universal concepts that, as you say later in your comment, you “learn once”. In that respect, it’s fair to leave them out. My only issue with it is that since F# doesn’t have higher-kinded types, these utility functions have to be specific to the monads and monad stacks in use. I originally thought this made such functions less understandable and less useful, but after reading the rest of your comment, I’m not sure they are. More on that below.</p> <blockquote><p>In your <em>evaluation</em></p> </blockquote> <p>(Emphasis yours.) Just in case: “Evaluation” might have been a poor choice of words. I hope you did not take it to mean that I was a teacher grading a student’s test. This was not in any way intended personally (e.g. evaluating &quot;<em>your</em> solution”). I was merely looking to sum up my subjective opinions about the refactoring.</p> <blockquote><p>Isn&#39;t it always worth it to take away accidental complexity?</p> </blockquote> <p>I find it hard to say an unequivocal &quot;yes” to such general statements. Ultimately it depends on the specific context and tradeoffs involved. If the context is “a codebase to be used for onboarding new F# devs” and the tradeoffs are “use generic helper functions to traverse bifunctors in a stack of monads”, then I’m not sure. (It <em>may</em> still be, but it’s certainly not a given.)</p> <p>But generally, though I haven’t reflected deeply on this, I’m sure you’re right that it’s worthwhile to always take away accidental complexity.</p> <blockquote><p><a href='https://blog.ploeh.dk/2019/12/09/put-cyclomatic-complexity-to-good-use/#de927bfcc95d410bbfcd0adf7a63926b'>No, it doesn&#39;t</a>. It has a cyclomatic complexity of <em>1</em>, exactly like the original humble object.</p> </blockquote> <p>You’re right. Thank you for the clarifying article on cyclomatic complexity.</p> <blockquote><blockquote><p>can&#39;t be easily tested</p> </blockquote> <p>True, but neither can the original humble object.</p> </blockquote> <p>That’s correct, but my point was that the original composition was trivial (just calling a “DI function” with the correct arguments/dependencies) and didn’t need to be tested, whereas the refactored composition does more and might warrant testing (at least to a larger degree than the original).</p> <p>This raises an interesting point. It seems (subjectively to me based on what I’ve read) to be a general consensus that a function can be left untested (is “humble”, so to speak) as long as it consists of just generic helpers, like the refactored composition. That &quot;if it compiles, it works”. This is not a general truth, since for some signatures there may exist several transformations from the input type to the output type, where the output value is different for the different transformations. I have come across such cases, and even had bugs because I used the wrong transformation. Which is why I said:</p> <blockquote><blockquote><p>The new composition is, so to say, quite a bit less humble than the original composition.</p> </blockquote> <p>According to which criterion?</p> </blockquote> <p>It is more complex in the sense that it doesn’t just call a function with the correct dependencies. The original composition is more or less immediately recognizable as correct. The refactored composition, as I said, required me to look at it more carefully to convince myself that it was correct. (I will grant that this is to some extent subjective, though.)</p> <blockquote><p>I don&#39;t like the epithet <em>non-standard</em>. It&#39;s true that these functions aren&#39;t in <code>FSharp.Core</code>, for reasons that aren&#39;t clear to me. In comparison, they&#39;re part of the standard <code>base</code> library in Haskell.</p> <p>There&#39;s nothing non-standard about functions like these. Like <code>map</code> and <code>bind</code>, traversals and catamorphisms are <a href='https://blog.ploeh.dk/2017/10/04/from-design-patterns-to-category-theory'>universal abstractions</a>. They exist independently of particular programming languages or library packages. </p> <p>I think that it&#39;s fair criticism that they may not be friendly to absolute beginners, but they&#39;re still fairly basic ideas that address real needs.</p> <p>…</p> <p>What I do, however, think is important to realise is that what I suggest is to learn a set of concepts <em>once</em>. Once you understand <a href='https://blog.ploeh.dk/2018/03/22/functors'>functors</a>, monads, traversals etcetera, that&#39;s knowledge that applies to F#, Haskell, C#, JavaScript (I suppose) and so on.</p> <p>Personally, I find it a better investment of my time to learn a general concept once, and then work with trivial code, rather than having to learn, over and over again, how to deal with each new code base&#39;s accidental complexity.</p> </blockquote> <p>This is the primary point of reflection for me in your comment. While I frequently use monads and monad stacks (particularly <code>Async&lt;Result&lt;_,_&gt;&gt;</code>) and often write utility code to transform when needed (e.g. <code>List.traverseResult</code>), I try to limit the number of such custom utility functions. Why? I’m not sure, actually. It may very well have to do with my work environment, where for a long time I have been the only F# dev and I don’t want to alienate the other .NET devs before they even get started with F#.</p> <p>In light of your comment, perhaps F# devs are doing others a disservice if we limit our use of important, general concepts like functors, monads, traversals etc.? Then again, there’s certainly a balance to be struck. I got started (and thrilled) with F# by reading <a href='https://fsharpforfunandprofit.com/'>F# for fun and profit</a> and learning about algebraic types, the concise syntax, &quot;railway-oriented programming” etc. If my first glimpse of F# had instead been <code>AsyncSeq.traverseAsyncResultOption</code>, then I might never have left the warm embrace of C#.</p> <p>I might check out <a href='http://fsprojects.github.io/FSharpPlus/'>FSharpPlus</a>, which seems to make this kind of programming easier. I have previously steered away from that library because I deemed it “too complex” (c.f. my remarks about alienating coworkers), but it might be time to reconsider. If you have tried it, I would love to hear your thoughts on it in some form or another, though admittedly that isn’t directly related to the topic at hand.</p> </div> <div class="comment-date">2019-12-12 9:04 UTC</div> </div> <div class="comment" id="477da2bf6ca04dc2ac478811cd77435e"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Christer, don't worry about the tone of the debate. I'm not in the least offended or vexed. On the contrary, I find this a valuable discussion, and I'm glad that we're having it in a medium where it's also visible to other people. </p> <p> I think that we're gravitating towards consensus. I definitely agree that the changes I suggest aren't beginner-friendly. </p> <p> People sometimes ask me for advice on how to get started with functional programming, and I always tell .NET developers to start with F#. It's a friendly language that enables everyone to learn gradually. If you already know C# (or Visual Basic .NET) the only thing you need to learn about F# is some syntax. Then you can write object-oriented F#. As you learn new functional concepts, you can gradually change the way you write F# code. That's what I did. </p> <p> I agree with your reservations about onboarding and beginner-friendliness. When that's a concern, I wouldn't write the F# code like I suggested either. </p> <p> For a more sophisticated team, however, I feel that my suggestions are improvements that matter. I grant you that the composition seems more convoluted, but I consider the overall trade-off beneficial. In the <a href="https://www.infoq.com/presentations/Simple-Made-Easy">terminology suggested by Rich Hickey</a>, it may not be easier, bit it's simpler. </p> <p> I have no experience with FSharpPlus or any similar libraries. I usually just add the monad stacks and functions to my code base on an as-needed basis. As we've seen here, such functions are mostly useful to compose other functions, so they rarely need to be exported as part of a code base's surface area. </p> </div> <div class="comment-date">2019-12-12 15:02 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>. TimeSpan configuration values in .NET Core https://blog.ploeh.dk/2019/11/25/timespan-configuration-values-in-net-core 2019-11-25T07:04:00+00:00 Mark Seemann <div id="post"> <p> <em>You can use a standard string format for TimeSpan values in configuration files.</em> </p> <p> Sometimes you need to make <code>TimeSpan</code> values configurable. I often see configuration files that look like this: </p> <p> <pre>{ &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;SeatingDurationInSeconds&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;9000&quot;</span> }</pre> </p> <p> Code can read such values from configuration files like this: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">seatingDuration</span>&nbsp;=&nbsp;<span style="color:#2b91af;">TimeSpan</span>.<span style="color:#74531f;">FromSeconds</span>(Configuration.<span style="font-weight:bold;color:#74531f;">GetValue</span>&lt;<span style="color:blue;">int</span>&gt;(<span style="color:#a31515;">&quot;SeatingDurationInSeconds&quot;</span>));</pre> </p> <p> This works, but is abstruse. How long is 9000 seconds? </p> <p> The <a href="/2015/08/03/idiomatic-or-idiosyncratic">idiomatic</a> configuration file format for .NET Core is JSON, which even prevents you from adding comments. Had the configuration been in XML, at least you could have added a comment: </p> <p> <pre><span style="color:blue;">&lt;!--</span><span style="color:green;">9000&nbsp;seconds&nbsp;=&nbsp;2½&nbsp;hours</span><span style="color:blue;">--&gt;</span> <span style="color:blue;">&lt;</span><span style="color:#a31515;">SeatingDurationInSeconds</span><span style="color:blue;">&gt;</span>9000<span style="color:blue;">&lt;/</span><span style="color:#a31515;">SeatingDurationInSeconds</span><span style="color:blue;">&gt;</span></pre> </p> <p> In this case, however, it doesn't matter. Use the <a href="https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-timespan-format-strings">standard TimeSpan string representation</a> instead: </p> <p> <pre>{ &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;SeatingDuration&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2:30:00&quot;</span> }</pre> </p> <p> Code can read the value like this: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">seatingDuration</span>&nbsp;=&nbsp;Configuration.<span style="font-weight:bold;color:#74531f;">GetValue</span>&lt;<span style="color:#2b91af;">TimeSpan</span>&gt;(<span style="color:#a31515;">&quot;SeatingDuration&quot;</span>);</pre> </p> <p> I find a configuration value like <code>"2:30:00"</code> much easier to understand than <code>9000</code>, and the end result is the same. </p> <p> I haven't found this documented anywhere, but from experience I know that this capability is present in the .NET Framework, so I wondered if it was also available in .NET Core. It is. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="95e18fd2054447ab901aecc4d74c1547"> <div class="comment-author">Rex Ng</div> <div class="comment-content"> <p>There is actually an <a href="https://en.wikipedia.org/wiki/ISO_8601#Durations">ISO 8601 standard for durations.</a></p> <p> In your example you can use <pre>{ "SeatingDuration": "P9000S" }</pre> or <pre>{ "SeatingDuration": "P2H30M" }</pre> which is also quite readable in my opinion.</p> <p>Not every JSON serializer supports it though.</p> </div> <div class="comment-date">2019-11-26 01:02 UTC</div> </div> <div class="comment" id="edb7484150934d94848fe923f0ee4a39"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Rex, thank you for writing. I was aware of the ISO standard, although I didn't know that you can use it in a .NET Core configuration file. This is clearly subjective, but I don't find that format as readable as <code>2:30:00</code>. </p> </div> <div class="comment-date">2019-11-26 6:59 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>. Small methods are easy to troubleshoot https://blog.ploeh.dk/2019/11/18/small-methods-are-easy-to-troubleshoot 2019-11-18T06:48:00+00:00 Mark Seemann <div id="post"> <p> <em>Write small methods. How small? Small enough that any unhandled exception is easy to troubleshoot.</em> </p> <p> Imagine that you receive a bug report. This one include a logged exception: </p> <p> <pre>System.NullReferenceException: Object reference not set to an instance of an object. at Ploeh.Samples.BookingApi.Validator.Validate(ReservationDto dto) at Ploeh.Samples.BookingApi.ReservationsController.Post(ReservationDto dto) at lambda_method(Closure , Object , Object[] ) at Microsoft.Extensions.Internal.ObjectMethodExecutor.Execute(Object target, Object[] parameters) at Microsoft.AspNetCore.Mvc.Internal.ActionMethodExecutor.SyncActionResultExecutor.Execute(IActionResultTypeMapper mapper, ObjectMethodExecutor executor, Object controller, Object[] arguments) at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.InvokeActionMethodAsync() at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.InvokeNextActionFilterAsync() at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.Rethrow(ActionExecutedContext context) at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.Next(State&amp; next, Scope&amp; scope, Object&amp; state, Boolean&amp; isCompleted) at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.InvokeInnerFilterAsync() at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeNextResourceFilter() at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.Rethrow(ResourceExecutedContext context) at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.Next(State&amp; next, Scope&amp; scope, Object&amp; state, Boolean&amp; isCompleted) at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeFilterPipelineAsync() at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeAsync() at Microsoft.AspNetCore.Builder.RouterMiddleware.Invoke(HttpContext httpContext) at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware.Invoke(HttpContext context) </pre> </p> <p> <em>Oh, no,</em> you think, <em>not a NullReferenceException.</em> </p> <p> If you find it hard to troubleshoot NullReferenceExceptions, you're not alone. It doesn't have to be difficult, though. Open the method at the top of the stack trace, <code>Validate</code>: </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;">Validator</span> { &nbsp;&nbsp;&nbsp;&nbsp;<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;{ &nbsp;&nbsp;&nbsp;&nbsp;&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;<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;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> Take a moment to consider this method in the light of the logged exception. What do you think went wrong? Which object was null? </p> <h3 id="efd0166dab0c4a85b23c624162f8da67"> Failed hypothesis <a href="#efd0166dab0c4a85b23c624162f8da67" title="permalink">#</a> </h3> <p> You may form one of a few hypotheses about which object was null. Could it be <code>dto</code>? <code>dto.Date</code>? Those are the only options I can see. </p> <p> When you encounter a bug in a production system, if at all possible, reproduce it as a unit test. </p> <p> If you think that the problem is that <code>dto.Date</code> is null, test your hypothesis 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;">ValidateNullDate</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:blue;">null</span>&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</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;">NotEmpty</span>(<span style="font-weight:bold;color:#1f377f;">actual</span>); }</pre> </p> <p> If you think that a null <code>dto.Date</code> should reproduce the above exception, you'd expect the test to fail. When you run it, however, it passes. It passes because <code>DateTime.TryParse(null, out var _)</code> returns <code>false</code>. It doesn't throw an exception. </p> <p> That's not the problem, then. </p> <p> That's okay, this sometimes happens. You form a hypothesis and fail to validate it. Reject it and move on. </p> <h3 id="e35877f1cc064a259b27046f05777807"> Validated hypothesis <a href="#e35877f1cc064a259b27046f05777807" title="permalink">#</a> </h3> <p> If the problem isn't with <code>dto.Date</code>, it must be with <code>dto</code> itself. Write a unit test to test that hypothesis: </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;">ValidateNullDto</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</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:blue;">null</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">NotEmpty</span>(<span style="font-weight:bold;color:#1f377f;">actual</span>); }</pre> </p> <p> When you run this test, it does indeed fail: </p> <p> <pre>Ploeh.Samples.BookingApi.UnitTests.ValidatorTests.ValidateNullDto Duration: 6 ms Message: System.NullReferenceException : Object reference not set to an instance of an object. Stack Trace: Validator.Validate(ReservationDto dto) line 12 ValidatorTests.ValidateNullDto() line 36</pre> </p> <p> This looks like the exception included in the bug report. You can consider this as validation of your hypothesis. This test reproduces the defect. </p> <p> It's easy to address the issue: </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="font-weight:bold;color:#1f377f;">dto</span>&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">&quot;No&nbsp;reservation&nbsp;data&nbsp;supplied.&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;<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> The point of this article, however, is to show that small methods are easy to troubleshoot. How you resolve the problem, once you've identified it, is up to you. </p> <h3 id="7b8e2476b4fb45a0b4f32b6b2d108724"> Ambiguity <a href="#7b8e2476b4fb45a0b4f32b6b2d108724" title="permalink">#</a> </h3> <p> Methods are usually more complex than the above example. Imagine, then, that you receive another bug report with this logged exception: </p> <p> <pre>System.NullReferenceException: Object reference not set to an instance of an object. at Ploeh.Samples.BookingApi.MaîtreD.CanAccept(IEnumerable`1 reservations, Reservation reservation) at Ploeh.Samples.BookingApi.ReservationsController.Post(ReservationDto dto) at lambda_method(Closure , Object , Object[] ) at Microsoft.Extensions.Internal.ObjectMethodExecutor.Execute(Object target, Object[] parameters) at Microsoft.AspNetCore.Mvc.Internal.ActionMethodExecutor.SyncActionResultExecutor.Execute(IActionResultTypeMapper mapper, ObjectMethodExecutor executor, Object controller, Object[] arguments) at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.InvokeActionMethodAsync() at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.InvokeNextActionFilterAsync() at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.Rethrow(ActionExecutedContext context) at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.Next(State&amp; next, Scope&amp; scope, Object&amp; state, Boolean&amp; isCompleted) at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.InvokeInnerFilterAsync() at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeNextResourceFilter() at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.Rethrow(ResourceExecutedContext context) at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.Next(State&amp; next, Scope&amp; scope, Object&amp; state, Boolean&amp; isCompleted) at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeFilterPipelineAsync() at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeAsync() at Microsoft.AspNetCore.Builder.RouterMiddleware.Invoke(HttpContext httpContext) at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware.Invoke(HttpContext context)</pre> </p> <p> When you open the code file for the <code>MaîtreD</code> class, this is what you see: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">capacity</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Capacity&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">capacity</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;Capacity&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="font-weight:bold;color:#74531f;">CanAccept</span>(<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">reservations</span>,&nbsp;<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;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservedSeats</span>&nbsp;=&nbsp;0; &nbsp;&nbsp;&nbsp;&nbsp;&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;">r</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">in</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservations</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">reservedSeats</span>&nbsp;+=&nbsp;<span style="font-weight:bold;color:#1f377f;">r</span>.Quantity; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(Capacity&nbsp;&lt;&nbsp;<span style="font-weight:bold;color:#1f377f;">reservedSeats</span>&nbsp;+&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>.Quantity) &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;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">true</span>; &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> This code throws a <code>NullReferenceException</code>, but which object is <code>null</code>? Can you identify it from the code? </p> <p> I don't think that you can. It could be <code>reservations</code> or <code>reservation</code> (or both). Without more details, you can't tell. The exception is ambiguous. </p> <p> The key to making troubleshooting easy is to increase your chances that, when exceptions are thrown, they're unambiguous. The problem with a <code>NullReferenceException</code> is that you can't tell which object was <code>null</code>. </p> <h3 id="6a46508d10734d5aaeaad9252e1f70ac"> Remove ambiguity by protecting invariants <a href="#6a46508d10734d5aaeaad9252e1f70ac" title="permalink">#</a> </h3> <p> Consider the <code>CanAccept</code> method. Clearly, it requires both <code>reservations</code> and <code>reservation</code> in order to work. This requirement is, however, currently implicit. You can make it more explicit by letting the method protect its invariants. (This is also known as <em>encapsulation</em>. For more details, watch my Pluralsight course <a href="https://blog.ploeh.dk/encapsulation-and-solid">Encapsulation and SOLID</a>.) </p> <p> A simple improvement is to add a <a href="https://en.wikipedia.org/wiki/Guard_(computer_science)">Guard Clause</a> for each argument: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="font-weight:bold;color:#74531f;">CanAccept</span>(<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">reservations</span>,&nbsp;<span style="color:#2b91af;">Reservation</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;">reservations</span>&nbsp;<span style="color:blue;">is</span>&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;">reservations</span>)); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">reservation</span>&nbsp;<span style="color:blue;">is</span>&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;">reservation</span>)); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservedSeats</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;">r</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">in</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservations</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">reservedSeats</span>&nbsp;+=&nbsp;<span style="font-weight:bold;color:#1f377f;">r</span>.Quantity; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(Capacity&nbsp;&lt;&nbsp;<span style="font-weight:bold;color:#1f377f;">reservedSeats</span>&nbsp;+&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:#8f08c4;">return</span>&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">true</span>; }</pre> </p> <p> If you'd done that from the start, the logged exception would instead have been this: </p> <p> <pre>System.ArgumentNullException: Value cannot be null. Parameter name: reservations at Ploeh.Samples.BookingApi.Ma&#xEE;treD.CanAccept(IEnumerable`1 reservations, Reservation reservation) at Ploeh.Samples.BookingApi.ReservationsController.Post(ReservationDto dto) at lambda_method(Closure , Object , Object[] ) at Microsoft.Extensions.Internal.ObjectMethodExecutor.Execute(Object target, Object[] parameters) at Microsoft.AspNetCore.Mvc.Internal.ActionMethodExecutor.SyncActionResultExecutor.Execute(IActionResultTypeMapper mapper, ObjectMethodExecutor executor, Object controller, Object[] arguments) at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.InvokeActionMethodAsync() at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.InvokeNextActionFilterAsync() at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.Rethrow(ActionExecutedContext context) at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.Next(State&amp; next, Scope&amp; scope, Object&amp; state, Boolean&amp; isCompleted) at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.InvokeInnerFilterAsync() at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeNextResourceFilter() at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.Rethrow(ResourceExecutedContext context) at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.Next(State&amp; next, Scope&amp; scope, Object&amp; state, Boolean&amp; isCompleted) at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeFilterPipelineAsync() at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeAsync() at Microsoft.AspNetCore.Builder.RouterMiddleware.Invoke(HttpContext httpContext) at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware.Invoke(HttpContext context)</pre> </p> <p> It's now clear that it was the <code>reservations</code> argument that was <code>null</code>. Now fix that issue. Why does the <code>CanAccept</code> receive a <code>null</code> argument? </p> <p> You may now consider examining the next frame in the stack trace: <code>ReservationsController.Post</code>: </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="color:blue;">var</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>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">validationMsg</span>&nbsp;!=&nbsp;<span style="color:#a31515;">&quot;&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="font-weight:bold;color:#1f377f;">validationMsg</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</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="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;">var</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>( &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;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">id</span>&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>(<span style="font-weight:bold;color:#1f377f;">id</span>); }</pre> </p> <p> The <code>Post</code> code only calls <code>CanAccept</code> once, so again, you can unambiguously deduce where the <code>null</code> reference comes from. It comes from the <code>Repository.ReadReservations</code> method call. Now go there and figure out why it returns <code>null</code>. </p> <p> Notice how troubleshooting is trivial when the methods are small. </p> <h3 id="952d4ebb24e94cb990ab1b047c4a7140"> Size matters <a href="#952d4ebb24e94cb990ab1b047c4a7140" title="permalink">#</a> </h3> <p> How small is a small method? How large does a method have to be before it's no longer small? </p> <p> <em>A method is small when you can easily troubleshoot it based exclusively on a logged exception.</em> </p> <p> Until you get the hang of it, it can be hard to predict if a method is going to be easy to troubleshoot. I therefore also follow another rule of thumb: </p> <p> For languages like C#, <a href="/2019/11/04/the-80-24-rule">methods should have a maximum size of 80x24 characters</a>. </p> <p> What if you already have bigger methods? Those are much harder to troubleshoot. If you have a method that spans hundreds of lines of code, a logged exception is rarely sufficient for troubleshooting. In order to save space, I'm not going to show en example of such a method, but I'm sure that you can easily find one in the code base that you professionally work with. Such a method is likely to have dozens of objects that could be <code>null</code>, so a <code>NullReferenceException</code> and a stack trace will contain too little information to assist troubleshooting. </p> <p> I often see developers add tracing or logging to such code in order to facilitate troubleshooting. This makes the code even more bloated, and harder to troubleshoot. </p> <p> Instead, cut the big method into smaller helper methods. You can keep the helper methods <code>private</code> so that you don't change the API. Even so, a logged exception will now report the helper method in its stack trace. Keep those helper methods small, and troubleshooting becomes trivial. </p> <h3 id="2a34a1a9c82443d8975a22fb9da9845b"> Conclusion <a href="#2a34a1a9c82443d8975a22fb9da9845b" title="permalink">#</a> </h3> <p> Small methods come with many benefits. One of these is that it's easy to troubleshoot a small method from a logged exception. Small methods typically take few arguments, and use few variables. A logged exception will often be all that you need to pinpoint where the problem occurred. </p> <p> A large method body, on the other hand, is difficult to troubleshoot. If all you have is a logged exception, you'll be able to find multiple places in the code where that exception could have been thrown. </p> <p> Refactor big methods into smaller helper methods. If one of these helper methods throws an exception, the method name will be included in the stack trace of a logged exception. When the helper method is small, you can easily troubleshoot it. </p> <p> Keep methods small. Size does matter. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="1734b6e6cd1b4898bf28c2412286f381"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> How did you create those exception stack traces? </p> <p> Compared to your examples, I am used to seeing each stack frame line end with the source code line number. (Although, sometimes I have seen all line numbers being 0, which is equivalent to having no line numbers at all.) The exception stack trace in your unit test includes line numbers but your other exception stack traces do not. This <a href="https://stackoverflow.com/questions/4272579/how-to-print-full-stack-trace-in-exception/4272629#4272629">Stack Overflow answer</a> contains an exception stack trace like with line numbers like I am used to seeing. </p> <p> The line containing "lambda_method" also seem odd to me. As I recall, invoking a lambda expression also contributes more information to the stack trace than your examples include. Although, that information is cryptic enough that I don't remember off the top of my head what it means. (After a quick search, I didn't find a good example of how I am used to seeing lambda expressions displayed in a stack trace.) </p> <p> With this additional informaiton, the methods can be longer while reamining unambiguous (in the sense you described). </p> </div> <div class="comment-date">2019-11-18 14:57 UTC</div> </div> <div class="comment" id="8a66b203db9245d8b3db5e40399f039e"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for writing. IIRC, you only see line numbers for code compiled with debug information. That's why you normally don't see line numbers for .NET base class library methods, ASP.NET Core, etc. </p> <p> While you can deploy and run an application in Debug mode, I wouldn't. When you compile in Release mode, the compiler makes optimisations (such as in-lining) that it can't do when it needs to retain a map to a specific source. In Debug mode, you squander those optimisations. </p> <p> I've always deployed systems in Release mode. To make the examples realistic, I didn't include the line numbers in the stack trace, because in Release mode, they aren't going to be there. </p> <p> When you're troubleshooting by reproducing a logged exception as a unit test, on the other hand, it's natural to do so in Debug mode. </p> </div> <div class="comment-date">2019-11-18 16:39 UTC</div> </div> <div class="comment" id="e2c03feb26854496b7d0ec528ea3ae8d"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> I just tried to verify this. I didn't find any difference between compiling in Debug or Release mode as well as no fundemental issue with in-lining. In all four cases (debug vs release and in-lining vs no inlining), exception stack traces still included line numbers. When in-lining, the only different was the absense of the in-lined method from the stack trace. </p> <p> Instead, I found that line numbers are included in exception stack traces if and only if the corresponding <a href="https://en.wikipedia.org/wiki/Program_database">.pdb</a> file is next to the .exe file when executed. </p> </div> <div class="comment-date">2019-11-18 19:07 UTC</div> </div> <div class="comment" id="2818246690a94b7b9c81ddfb47fc6d89"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, that sounds correct. To be honest, I stopped putting effort into learning advanced debugging skills a long time ago. Early in my career we debugged by writing debug statements directly to output! Then I learned test-driven development, and with that disappeared most of the need to debug full systems. At the time I began working with systems that logged unhandled exceptions, the habit of writing small methods was already so entrenched that I never felt that I needed the line numbers. </p> <p> FWIW, more than five years ago, I decided to <a href="https://github.com/AutoFixture/AutoFixture/issues/65">publish symbols with AutoFixture</a>, but I never found it useful. </p> </div> <div class="comment-date">2019-11-19 7:18 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>. Diamond rock https://blog.ploeh.dk/2019/11/11/diamond-rock 2019-11-11T09:15:00+00:00 Mark Seemann <div id="post"> <p> <em>A diamond kata implementation written in Rockstar</em> </p> <p> I've <a href="/2015/01/10/diamond-kata-with-fscheck">previously written about the diamond kata</a>, which has become one of my favourite programming exercises. I wanted to take the <a href="https://codewithrockstar.com">Rockstar</a> language out for a spin, and it seemed a good candidate problem. </p> <h3 id="ab491bf89ae945f48821fe7b324febeb"> Rockstar <a href="#ab491bf89ae945f48821fe7b324febeb" title="permalink">#</a> </h3> <p> If you're not aware of the Rockstar programming language, it started with a tweet from <a href="http://paulstovell.com">Paul Stovell</a>: <blockquote> <p> "To really confuse recruiters, someone should make a programming language called Rockstar." </p> <footer><cite><a href="https://twitter.com/paulstovell/status/1013960369465782273">Paul Stovell</a></cite></footer> </blockquote> This inspired <a href="http://www.dylanbeattie.net">Dylan Beattie</a> to create the Rockstar programming language. The language's <a href="https://codewithrockstar.com">landing page</a> already sports an <a href="/2015/08/03/idiomatic-or-idiosyncratic">idiomatic</a> implementation of the <a href="http://codingdojo.org/kata/FizzBuzz">FizzBuzz kata</a>, so I had to pick another exercise. The <a href="http://claysnow.co.uk/recycling-tests-in-tdd">diamond kata</a> was a natural choice for me. </p> <h3 id="c17e0b1d17f04d19b9e965ad531f10d9"> Lyrics <a href="#c17e0b1d17f04d19b9e965ad531f10d9" title="permalink">#</a> </h3> <p> I'll start with the final result. What follows here are the final lyrics to <em>Diamond rock</em>. As you'll see, it starts with a short prologue after which it settles into a repetitive pattern. I imagine that this might make it useful for audience participation, in the anthem rock style of e.g. <a href="https://en.wikipedia.org/wiki/We_Will_Rock_You">We Will Rock You</a>. </p> <p> After 25 repetitions the lyrics change. I haven't written music to any of them, but I imagine that this essentially transitions into another song, just like <em>We Will Rock You</em> traditionally moves into <a href="https://en.wikipedia.org/wiki/We_Are_the_Champions">We Are the Champions</a>. The style of the remaining lyrics does, however, suggest something musically more complex than a rock anthem. </p> <p> <pre>Your memory says&nbsp;&nbsp; The way says A Despair takes your hope The key is nothing Your courage is a tightrope Let it be without it If your hope is your courage Let the key be the way Build your courage up If your hope is your courage The key says B Build your courage up If your hope is your courage The key says C Build your courage up If your hope is your courage The key says D Build your courage up If your hope is your courage The key says E Build your courage up If your hope is your courage The key says F Build your courage up If your hope is your courage The key says G Build your courage up If your hope is your courage The key says H Build your courage up If your hope is your courage The key says I Build your courage up If your hope is your courage The key says J Build your courage up If your hope is your courage The key says K Build your courage up If your hope is your courage The key says L Build your courage up If your hope is your courage The key says M Build your courage up If your hope is your courage The key says N Build your courage up If your hope is your courage The key says O Build your courage up If your hope is your courage The key says P Build your courage up If your hope is your courage The key says Q Build your courage up If your hope is your courage The key says R Build your courage up If your hope is your courage The key says S Build your courage up If your hope is your courage The key says T Build your courage up If your hope is your courage The key says U Build your courage up If your hope is your courage The key says V Build your courage up If your hope is your courage The key says W Build your courage up If your hope is your courage The key says X Build your courage up If your hope is your courage The key says Y Build your courage up If your hope is your courage The key says Z Give back the key Dream takes a tightrope Your hope's start'n'stop While Despair taking your hope ain't a tightrope Build your hope up Give back your hope Raindrop is a wintercrop Light is a misanthrope Let it be without raindrop Darkness is a kaleidoscope Let it be without raindrop Diamond takes your hour, love, and your day If love is the way Let your sorrow be your hour without light Put your sorrow over darkness into flight Put your memory of flight into motion Put it with love, and motion into the ocean Whisper the ocean If love ain't the way Let ray be your day of darkness without light Let your courage be your hour without darkness, and ray Put your courage over darkness into the night Put your memory of ray into action Let satisfaction be your memory of the night Let alright be satisfaction with love, action, love, and satisfaction Shout alright Listen to the wind Let flight be the wind Let your heart be Dream taking flight Let your breath be your heart of darkness with light Your hope's stop'n'start While your hope is lower than your heart Let away be Despair taking your hope Diamond taking your breath, away, and your hope Build your hope up Renown is southbound While your hope is as high as renown Let away be Despair taking your hope Diamond taking your breath, away, and your hope Knock your hope down</pre> </p> <p> Not only do these look like lyrics, but it's also an executable program! </p> <h3 id="994b9a9d46dc467383c528a17dc99f65"> Execution <a href="#994b9a9d46dc467383c528a17dc99f65" title="permalink">#</a> </h3> <p> If you want to run the program, you can copy the text and paste it into <a href="https://codewithrockstar.com/online">the web-based Rockstar interpreter</a>; that's what I did. </p> <p> When you <em>Rock!</em> the lyrics, the interpreter will prompt you for an input. There's no instructions or input validation, but <em>the only valid input is the letters</em> <code>A</code> to <code>Z</code>, and <em>only in upper case</em>. If you type anything else, I don't know what'll happen, but most likely it'll just enter an infinite loop, and you'll have to reboot your computer. </p> <p> If you input, say, <code>E</code>, the output will be the expected diamond figure: </p> <p> <pre> A B B C C D D E E D D C C B B A </pre> </p> <p> When you paste the code, be sure to include everything. There's significant whitespace in those lyrics; I'll explain later. </p> <h3 id="12f2c388f5c8499594a3bf90f37e07f4"> Readable code <a href="#12f2c388f5c8499594a3bf90f37e07f4" title="permalink">#</a> </h3> <p> As the Rockstar documentation strongly implies, <em>singability</em> is more important than readability. You can, however, write more readable Rockstar code, and that's what I started with: </p> <p> <pre>Space says&nbsp;&nbsp; LetterA says A GetLetter takes index If index is 0 Give back LetterA If index is 1 retVal says B Give back retVal If index is 2 retVal says C Give back retVal GetIndex takes letter Index is 0 While GetLetter taking Index ain't letter Build Index up Give back Index PrintLine takes width, l, lidx If l is LetterA Let completeSpaceCount be width minus 1 Let paddingCount be completeSpaceCount over 2 Let padding be Space times paddingCount Let line be padding plus l plus padding Say line Else Let internalSpaceSize be lidx times 2 minus 1 Let filler be Space times internalSpaceSize Let totalOuterPaddingSize be width minus 2, internalSpaceSize Let paddingSize be totalOuterPaddingSize over 2 Let padding be Space times paddingSize Let line be padding plus l, filler, l, padding Say line Listen to input Let idx be GetIndex taking input Let width be idx times 2 plus 1 Let counter be 0 While counter is lower than idx Let l be GetLetter taking counter PrintLine taking width, l, counter Build counter up While counter is as high as 0 Let l be GetLetter taking counter PrintLine taking width, l, counter Knock counter down</pre> </p> <p> This prototype only handled the input letters <code>A</code>, <code>B</code>, and <code>C</code>, but it was enough to verify that the algorithm worked. I've done the diamond kata several times before, so I only had to find the most imperative implementation on my hard drive. It wasn't too hard to translate to Rockstar. </p> <p> Although Rockstar supports mainstream quoted strings like <code>"A"</code>, <code>"B"</code>, and so on, you can see that I went straight for <em>poetic string literals</em>. Before I started persisting Rockstar code to a file, I experimented with the language using the online interpreter. I wanted the program to look as much like rock lyrics as I could, so I didn't want to have too many statements like <code>Shout "FizzBuzz!"</code> in my code. </p> <h3 id="1ae1c1c329894b438bc934097090901b"> Obscuring space <a href="#1ae1c1c329894b438bc934097090901b" title="permalink">#</a> </h3> <p> My first concern was whether I could obscure the space character. Using a poetic string literal, I could: </p> <p> <pre>Space says&nbsp;&nbsp;</pre> </p> <p> The rules of poetic string literals is that everything between <code>says&nbsp;</code> and the newline character becomes the value of the string variable. So there's an extra space after <code>says&nbsp;</code>! </p> <p> After I renamed all the variables and functions, that line became: </p> <p> <pre>Your memory says&nbsp;&nbsp;</pre> </p> <p> Perhaps it isn't an unprintable character, but it <em>is</em> unsingable. </p> <h3 id="d1ae4568cc104312a3c20fe8019ccb18"> No else <a href="#d1ae4568cc104312a3c20fe8019ccb18" title="permalink">#</a> </h3> <p> The keyword <code>Else</code> looks conspicuously like a programming construct, so I wanted to get rid of that as well. That was easy, because I could just invert the initial <code>if</code> condition: </p> <p> <pre>If l ain't LetterA</pre> </p> <p> This effectively switches between the two alternative code blocks. </p> <h3 id="cbaa9c218905453bb3df2155b9e9b822"> Obscuring letter indices <a href="#cbaa9c218905453bb3df2155b9e9b822" title="permalink">#</a> </h3> <p> I also wanted to obscure the incrementing index values <code>1</code>, <code>2</code>, <code>3</code>, etcetera. Since the indices are monotonically increasing, I realised that I could use a counter and increment it: </p> <p> <pre>number is 0 If index is number Let retVal be LetterA Build number up If index is number retVal says B Build number up If index is number retVal says C</pre> </p> <p> The function initialises <code>number</code> to <code>0</code> and assigns a value to <code>retVal</code> if the input <code>index</code> is also <code>0</code>. </p> <p> If not, it increments the <code>number</code> (so that it's now <code>1</code>) and again compares it to <code>index</code>. This sufficiently obscures the indices, but if there's a way to hide the letters of the alphabet, I'm not aware of it. </p> <p> After I renamed the variables, the code became: </p> <p> <pre>Your courage is a tightrope Let it be without it If your hope is your courage Let the key be the way Build your courage up If your hope is your courage The key says B Build your courage up If your hope is your courage The key says C</pre> </p> <p> There's one more line of code in the final lyrics, compared to the above snippet. The line <code>Let it be without it</code> has no corresponding line of code in the readable version. What's going on? </p> <h3 id="aef4cf50f4484327b37cd61995c74d99"> Obscuring numbers <a href="#aef4cf50f4484327b37cd61995c74d99" title="permalink">#</a> </h3> <p> Like poetic string literals, Rockstar also supports <em>poetic number literals</em>. Due to its modulo-ten-based system, however, I found it difficult to come up with a good ten-letter word that fit the song's lyrical theme. I <em>could</em> have done something like this to produce the number <code>0</code>: </p> <p> <pre>Your courage is barbershop</pre> </p> <p> or some other ten-letter word. My problem was that regardless of what I chose, it didn't sound good. Some article like <code>a</code> or <code>the</code> would sound better, but that would change the value of the poetic number literal. <code>a tightrope</code> is the number <em>19</em>, because <code>a</code> has one letter, and <code>tightrope</code> has nine. </p> <p> There's a simple way to produce <em>0</em> from any number: just subtract the number from itself. That's what <code>Let it be without it</code> does. I could also have written it as <code>Let your courage be without your courage</code>, but I chose to take advantage of Rockstar's <em>pronoun</em> feature instead. I'd been looking for an opportunity to include the phrase <a href="https://en.wikipedia.org/wiki/Let_It_Be_(Beatles_song)">Let It Be</a> ever since I learned about the <code>Let x be y</code> syntax. </p> <p> The following code snippet initialises the variable <code>Your courage</code> to <code>19</code>, but on the next line subtracts 19 from 19 and updates the variable so that its value is now <code>0</code>. </p> <p> <pre>Your courage is a tightrope Let it be without it</pre> </p> <p> I had the same problem with initialising the numbers <em>1</em> and <em>2</em>, so further down I resorted to similar tricks: </p> <p> <pre>Raindrop is a wintercrop Light is a misanthrope Let it be without raindrop Darkness is a kaleidoscope Let it be without raindrop </pre> </p> <p> Here I had the additional constraint that I wanted the words to rhyme. The rhymes are a continuation of the previous lines' <code>up</code> and <code>hope</code>, so I struggled to come up with a ten-letter word that rhymes with <code>up</code>; <code>wintercrop</code> was the best I could do. <code>a wintercrop</code> is <em>10</em>, and the strategy is to define <code>Light</code> and <code>Darkness</code> as <em>11</em> and <em>12</em>, and then subtract <em>10</em> from both. At the first occurrence of <code>Let it be without raindrop</code>, <code>it</code> refers to <code>Light</code>, whereas the second time <code>it</code> refers to <code>Darkness</code>. </p> <h3 id="46b60c0d25e54f9599e5bd40b7e88d80"> Lyrical theme <a href="#46b60c0d25e54f9599e5bd40b7e88d80" title="permalink">#</a> </h3> <p> Once I had figured out how to obscure strings and numbers, it was time to rename all the readable variables and function names into idiomatic Rockstar. </p> <p> At first, I thought that I'd pattern my lyrics after <a href="https://en.wikipedia.org/wiki/Shine_On_You_Crazy_Diamond">Shine On You Crazy Diamond</a>, but I soon ran into problems with the keyword <code>taking</code>. I found it difficult to find words that would naturally succeed <code>taking</code>. Some options I thought of were: <ul> <li>taking the bus</li> <li>taking a chance</li> <li>taking hold</li> <li>taking flight</li> <li>taking time</li> </ul> Some of these didn't work for various reasons. In Rockstar <code>times</code> is a keyword, and apparently <code>time</code> is reserved as well. At least, the online interpreter choked on it. </p> <p> <code>Taking a chance</code> sounded <a href="https://en.wikipedia.org/wiki/Take_a_Chance_on_Me">too much like ABBA</a>. <code>Taking hold</code> created the derived problem that I had to initialise and use a variable called <code>hold</code>, and I couldn't make that work. </p> <p> <code>Taking flight</code>, on the other hand, turned out to provide a fertile opening. </p> <p> I soon realised, though, that my choice of words pulled the lyrical theme away from idiomatic Rockstar vocabulary. While I do get the <a href="https://en.wikipedia.org/wiki/Livin%27_on_a_Prayer">Tommy and Gina</a> references, I didn't feel at home in that poetic universe. </p> <p> On the other hand, I thought that the words started to sound like <a href="https://en.wikipedia.org/wiki/Yes_(band)">Yes</a>. I've listened to a lot of Yes. The lyrics are the same kind of lame and vapid as what was taking form in my editor. I decided to go in that direction. </p> <p> Granted, this is no longer idiomatic Rockstar, since it's more <a href="https://en.wikipedia.org/wiki/Progressive_rock">prog rock</a> than <a href="https://en.wikipedia.org/wiki/Glam_metal">hair metal</a>. I invoke creative license. </p> <p> Soon I also conceived of the extra ambition that I wanted the verses to rhyme. Here, it proved fortunate that the form <code>let x be y</code> is interchangeable with the form <code>put y into x</code>. Some words, like <em>darkness</em>, are difficult to rhyme with, so it helps that you can hide them within a <code>put y into x</code> form. </p> <p> Over the hours(!) I worked on this, a theme started to emerge. I'm particularly fond of the repeated motifs like: </p> <p> <pre>Your hope's start'n'stop</pre> </p> <p> which rhymes with <code>up</code>, but then later it appears again as </p> <p> <pre>Your hope's stop'n'start</pre> </p> <p> which rhymes with <code>heart</code>. Both words, by the way, represent the number <em>0</em>, since there's ten letters when you ignore the single quotes. </p> <h3 id="234366a7cb1a4998813719845f3c08d7"> Conclusion <a href="#234366a7cb1a4998813719845f3c08d7" title="permalink">#</a> </h3> <p> I spent more time on this that I suppose I ought to, but once I got started, it was hard to stop. I found the translation from readable code into 'idiomatic' Rockstar at least as difficult as writing working software. There's a lesson there, I believe. </p> <p> Rockstar is still a budding language, so I did miss a few features, chief among which would be <em>arrays</em>, but I'm not sure how one would make arrays sufficiently rock'n'roll. </p> <p> A unit testing framework would also be nice. </p> <p> If you liked this article, please <a href="https://www.linkedin.com/in/ploeh/">endorse my <em>Rockstar</em> skills on LinkedIn</a> so that we can <em>"confuse recruiters."</em> </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 80/24 rule https://blog.ploeh.dk/2019/11/04/the-80-24-rule 2019-11-04T06:51:00+00:00 Mark Seemann <div id="post"> <p> <em>Write small blocks of code. How small? Here's how small.</em> </p> <p> One of the most common questions I get is this: </p> <p> <em>If you could give just one advice to programmers, what would it be?</em> </p> <p> That's easy: </p> <p> <em>Write small blocks of code.</em> </p> <p> Small methods. Small functions. Small procedures. </p> <p> How small? </p> <h3 id="849d07675e3a4c5681641eb0c67dfafb"> Few lines of code <a href="#849d07675e3a4c5681641eb0c67dfafb" title="permalink">#</a> </h3> <p> You can't give a universally good answer to that question. Among other things, it depends on the programming language in question. Some languages are much denser than others. The densest language I've ever encountered is <a href="https://en.wikipedia.org/wiki/APL_(programming_language)">APL</a>. </p> <p> Most mainstream languages, however, seem to be verbose to approximately the same order of magnitude. My experience is mostly with C#, so I'll use that (and similar languages like Java) as a starting point. </p> <p> When I write C# code, I become uncomfortable when my method size approaches fifteen or twenty lines of code. C# is, however, a fairly wordy language, so it sometimes happens that I have to allow a method to grow larger. My limit is probably somewhere around 25 lines of code. </p> <p> That's an arbitrary number, but if I have to quote a number, it would be around that size. Since it's arbitrary anyway, let's make it <em>24</em>, for reasons that I'll explain later. </p> <p> The maximum line count of a C# (or Java, or JavaScript, etc.) method, then, should be 24. </p> <p> To repeat the point from before, this depends on the language. I'd consider a 24-line <a href="https://www.haskell.org">Haskell</a> or <a href="https://fsharp.org">F#</a> function to be so huge that if I received it as a pull request, I'd reject it <a href="/2015/01/15/10-tips-for-better-pull-requests">on the grounds of size</a> alone. </p> <h3 id="8506ebcba585459b9739d84a7bcad758"> Narrow line width <a href="#8506ebcba585459b9739d84a7bcad758" title="permalink">#</a> </h3> <p> Most languages allow for flexibility in layout. For example, C-based languages use the <code>;</code> character as a delimiter. This enables you to write more than one statement per line: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">foo</span>&nbsp;=&nbsp;32;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">bar</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">foo</span>&nbsp;+&nbsp;10;&nbsp;<span style="color:#2b91af;">Console</span>.<span style="color:#74531f;">WriteLine</span>(<span style="font-weight:bold;color:#1f377f;">bar</span>);</pre> </p> <p> You could attempt to avoid the 24-line-height rule by writing wide lines. That would, however, be to defeat the purpose. </p> <p> The purpose of writing small methods is to nudge yourself towards writing readable code; code that fits in your brain. The smaller, the better. </p> <p> For completeness sake, let's institute a maximum line width as well. If there's any accepted industry standard for maximum line width, it's 80 characters. I've used that maximum for years, and it's a good maximum. </p> <p> Like all other programmers, other people's code annoys me. The most common annoyance is that people write too wide code. </p> <p> This is probably because most programmers have drunk the Cool Aid that bigger screens make you more productive. When you code on a big screen, you don't notice how wide your lines become. </p> <p> There's many scenarios where wide code is problematic: <ul> <li>When you're comparing changes to a file side-by-side. This often happens when you review pull requests. Now you have only half of your normal screen width.</li> <li>When you're looking at code on a smaller device.</li> <li>When you're getting old, or are otherwise visually impaired. After I turned 40, I discovered that I found it increasingly difficult to see small things. I still use a 10-point font for programming, but I foresee that this will not last much longer.</li> <li>When you're <a href="https://en.wikipedia.org/wiki/Mob_programming">mob programming</a> you're limited to the size of the shared screen.</li> <li>When you're sharing your screen via the web, for remote pair programming or similar.</li> <li>When you're presenting code at meetups, user groups, conferences, etc.</li> </ul> What most programmers need, I think, is just a <a href="https://en.wikipedia.org/wiki/Nudge_theory">nudge</a>. In Visual Studio, for example, you can install the <a href="https://marketplace.visualstudio.com/items?itemName=PaulHarrington.EditorGuidelines">Editor Guidelines</a> extension, which will display one or more vertical guidelines. You can configure it as you'd like, but I've mine set to 80 characters, and bright red: </p> <p> <img src="/content/binary/vertical-guideline-at-80-characters.png" alt="Screen shot of editor with code, showing red vertical line at 80 characters."> </p> <p> Notice the red dotted vertical line that cuts through <code>universe</code>. It tells me where the 80 character limit is. </p> <h3 id="d94a52940215425e9cb19492d9f51a41"> Terminal box <a href="#d94a52940215425e9cb19492d9f51a41" title="permalink">#</a> </h3> <p> The 80-character limit has a long and venerable history, but what about the 24-line limit? While both are, ultimately, arbitrary, both fit the size of the popular <a href="https://en.wikipedia.org/wiki/VT100">VT100</a> terminal, which had a display resolution of 80x24 characters. </p> <p> A box of 80x24 characters thus reproduces the size of an old terminal. Does this mean that I suggest that you should write programs on terminals? No, people always misunderstand this. That should be the maximum size of a method. On larger screens, you'd be able to see multiple small methods at once. For example, you could view a unit test and its target in a split screen configuration. </p> <p> The exact sizes are arbitrary, but I think that there's something fundamentally right about such continuity with the past. </p> <p> I've been using the 80-character mark as a soft limit for years. I tend to stay within it, but I occasionally decide to make my code a little wider. I haven't paid quite as much attention to the number of lines of my methods, but only for the reason that I know that I tend to write methods shorter than that. Both limits have served me well for years. </p> <h3 id="e5301bcefd8f444487906af03df293b0"> Example <a href="#e5301bcefd8f444487906af03df293b0" title="permalink">#</a> </h3> <p> Consider this example: </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="color:blue;">var</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>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">validationMsg</span>&nbsp;!=&nbsp;<span style="color:#a31515;">&quot;&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="font-weight:bold;color:#1f377f;">validationMsg</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</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="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;">var</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>( &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;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">id</span>&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>(<span style="font-weight:bold;color:#1f377f;">id</span>); }</pre> </p> <p> This method is 18 lines long, which includes the method declaration, curly brackets and blank lines. It easily stays within the 80-character limit. Note that I've deliberately formatted the code so that it behaves. You can see it in this fragment: </p> <p> <pre><span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">StatusCode</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">StatusCodes</span>.Status500InternalServerError, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;Couldn&#39;t&nbsp;accept.&quot;</span>);</pre> </p> <p> Most people write it like this: </p> <p> <pre><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>);</pre> </p> <p> That doesn't look bad, but I've seen much worse examples. </p> <p> Another key to writing small methods is to call other methods. The above <code>Post</code> method doesn't look like much, but significant functionality could be hiding behind <code>Validator.Validate</code>, <code>Repository.ReadReservations</code>, or <code>maîtreD.CanAccept</code>. I hope that you agree that each of these objects and methods are named well enough to give you an idea about their purpose. </p> <h3 id="ca4e5a8403244f93a95c2736cdaf7eee"> Code that fits in your brain <a href="#ca4e5a8403244f93a95c2736cdaf7eee" title="permalink">#</a> </h3> <p> As I describe in my <a href="https://cleancoders.com/episode/humane-code-real-episode-1/show">Humane Code</a> video, the human brain can only keep track of <a href="https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two">about seven things</a>. I think that this rule of thumb applies to the way we read and interpret code. If you need to understand and keep track of more than seven separate things at the same time, the code becomes harder to understand. </p> <p> This could explain why small methods are good. They're only good, however, if they're self-contained. When you look at a method like the above <code>Post</code> method, you'll be most effective if you don't need to have a deep understanding of how each of the dependencies work. If this is true, the method only juggles about five dependencies: <code>Validator</code>, <code>Mapper</code>, <code>Repository</code>, <code>maîtreD</code>, and its own base class (which provides the methods <code>BadRequest</code>, <code>StatusCode</code>, and <code>Ok</code>). Five dependencies is fewer than seven. </p> <p> Another way to evaluate the cognitive load of a method is to measure its <a href="https://en.wikipedia.org/wiki/Cyclomatic_complexity">cyclomatic complexity</a>. The <code>Post</code> method's cyclomatic complexity is <em>3</em>, so that should be easily within the brain's capacity. </p> <p> These are all heuristics, so read this for inspiration, not as law. They've served me well for years, though. </p> <h3 id="1c2120e143784dde8e520026b67651d4"> Conclusion <a href="#1c2120e143784dde8e520026b67651d4" title="permalink">#</a> </h3> <p> You've probably heard about the <em>80/20 rule</em>, also known as the <a href="https://en.wikipedia.org/wiki/Pareto_principle">Pareto principle</a>. Perhaps the title lead you to believe that this article was a misunderstanding. I admit that I went for an arresting title; perhaps a more proper name is the <em>80x24 rule</em>. </p> <p> The exact numbers can vary, but I've found a maximum method size of 80x24 characters to work well for C#. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="cbdf43b5551242efa330a163f01119ca"> <div class="comment-author">Jiehong</div> <div class="comment-content"> <p> As a matter of fact, <em>terminals</em> had 80 characters lines, because <a href="https://en.wikipedia.org/wiki/Punched_card#/media/File:FortranCardPROJ039.agr.jpg">IBM punch cards</a>, representing only 1 line, had 80 symbols (even though only the first 72 were used at first). However, I don't know why terminals settled for 24 lines! In Java, which is similar to C# in term of verbosity, Clean Code tend to push towards 20-lines long functions or less. One of the danger to make functions even smaller is that many more functions can create many indirections, and that becomes harder to keep track within our brains. </p> </div> <div class="comment-date">2019-11-04 11:13 UTC</div> </div> <div class="comment" id="7fc45f8fd537ba9907ad73daa2c85b52"> <div class="comment-author">Terrell</div> <div class="comment-content"> <p> Some additional terminal sizing history in Mike Hoye's recent similarly-named post: <a href="http://exple.tive.org/blarg/2019/10/23/80x25/">http://exple.tive.org/blarg/2019/10/23/80x25/</a> Spoiler - Banknotes! </p> </div> <div class="comment-date">2019-11-04 13:25 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>. A basic Haskell solution to the robot journeys coding exercise https://blog.ploeh.dk/2019/10/28/a-basic-haskell-solution-to-the-robot-journeys-coding-exercise 2019-10-28T04:34:00+00:00 Mark Seemann <div id="post"> <p> <em>This article shows an idiomatic, yet beginner-friendly Haskell solution to a coding exercise.</em> </p> <p> <a href="https://twitter.com/mikehadlow/status/1186332184086495233">Mike Hadlow tweeted</a> a coding exercise that involves parsing and evaluating instruction sets. <a href="https://www.haskell.org">Haskell</a> excels at such problems, so I decided to give it a go. Since this was only an exercise for the fun of it, I didn't want to set up a complete Haskell project. Rather, I wanted to write one or two <code>.hs</code> files that I could interact with via <em>GHCi</em>. This means no lenses, monad transformers, or other fancy libraries. </p> <p> Hopefully, this makes the code friendly to Haskell beginners. It shows what I consider <a href="/2015/08/03/idiomatic-or-idiosyncratic">idiomatic</a>, but basic Haskell, solving a problem of moderate difficulty. </p> <h3 id="79b308125b2d4bcc9df79f7c6569a6e9"> The problem <a href="#79b308125b2d4bcc9df79f7c6569a6e9" title="permalink">#</a> </h3> <p> <a href="https://github.com/mikehadlow/Journeys">Mike Hadlow has a detailed description of the exercise</a>, but in short, you're given a file with a set of instructions that look like this: </p> <p> <pre>1 1 E RFRFRFRF 1 1 E</pre> </p> <p> The first and last lines describe the position and orientation of a robot. The first line, for example, describes a robot at position (1, 1) facing east. A robot can face in one of the four normal directions of the map: north, east, south, and west. </p> <p> The first line gives the robot's start position, and the last line the <em>expected</em> end position. </p> <p> The middle line is a set of instructions to the robot. It can turn left or right, or move forward. </p> <p> The exercise is to evaluate whether journeys are valid; that is, whether the robot's end position matches the expected end position if it follows the commands. </p> <h3 id="cf43d781d49545c38e30f487867e904f"> Imports <a href="#cf43d781d49545c38e30f487867e904f" title="permalink">#</a> </h3> <p> I managed to solve the exercise with a single <code>Main.hs</code> file. Here's the module declaration and the required imports: </p> <p> <pre><span style="color:blue;">module</span>&nbsp;Main&nbsp;<span style="color:blue;">where</span> <span style="color:blue;">import</span>&nbsp;Data.Foldable <span style="color:blue;">import</span>&nbsp;Data.Ord <span style="color:blue;">import</span>&nbsp;Text.Read&nbsp;(<span style="color:#2b91af;">readPrec</span>) <span style="color:blue;">import</span>&nbsp;Text.ParserCombinators.ReadP <span style="color:blue;">import</span>&nbsp;Text.ParserCombinators.ReadPrec&nbsp;(<span style="color:#2b91af;">readPrec_to_P</span>,&nbsp;<span style="color:#2b91af;">minPrec</span>)</pre> </p> <p> These imports are only required to support parsing of input. Once parsed, you can evaluate each journey using nothing but the functions available in the standard <code>Prelude</code>. </p> <h3 id="8329bba327f54dbfb8474f9102ba8662"> Types <a href="#8329bba327f54dbfb8474f9102ba8662" title="permalink">#</a> </h3> <p> Haskell is a statically typed language, so it often pays to define some types. Granted, the exercise hardly warrants all of these types, but as an example of idiomatic Haskell, I think that this is still good practice. After all, Haskell types are easy to declare. Often, they are one-liners: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;Direction&nbsp;=&nbsp;North&nbsp;|&nbsp;East&nbsp;|&nbsp;South&nbsp;|&nbsp;West&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>)</pre> </p> <p> The <code>Direction</code> type enumerates the four corners of the world. </p> <p> <pre><span style="color:blue;">data</span>&nbsp;Robot&nbsp;=&nbsp;Robot&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;robotPosition&nbsp;::&nbsp;(Integer,&nbsp;Integer) &nbsp;&nbsp;,&nbsp;robotDirection&nbsp;::&nbsp;Direction&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>)</pre> </p> <p> The <code>Robot</code> record type represents the state of a robot: its position and the direction it faces. </p> <p> You'll also need to enumerate the commands that you can give a robot: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;Command&nbsp;=&nbsp;TurnLeft&nbsp;|&nbsp;TurnRight&nbsp;|&nbsp;MoveForward&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>)</pre> </p> <p> Finally, you can also define a type for a <code>Journey</code>: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;Journey&nbsp;=&nbsp;Journey&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;journeyStart&nbsp;::&nbsp;Robot &nbsp;&nbsp;,&nbsp;journeyCommands&nbsp;::&nbsp;[Command] &nbsp;&nbsp;,&nbsp;journeyEnd&nbsp;::&nbsp;Robot&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>)</pre> </p> <p> These are all the types required for solving the exercise. </p> <h3 id="5ada3f24aa4e4858892855ae076f457b"> Parsing <a href="#5ada3f24aa4e4858892855ae076f457b" title="permalink">#</a> </h3> <p> The format of the input file is simple enough that it could be done in an ad-hoc fashion using <code>lines</code>, <code>word</code>, <code>read</code>, and a few other low-level functions. While the format barely warrants the use of parser combinators, I'll still use some to showcase the power of that approach. </p> <p> Since one of my goals is to implement the functionality using a single <code>.hs</code> file, I can't pull in external parser combinator libraries. Instead, I'll use the built-in <code>ReadP</code> module, which I've often found sufficient to parse files like the present exercise input file. </p> <p> First, you're going to have to be able to parse numbers, which can be done using the <code>Read</code> type class. You'll need, however, to be able to compose <code>Integer</code> parsers with other <code>ReadP</code> parsers. </p> <p> <pre><span style="color:#2b91af;">parseRead</span>&nbsp;::&nbsp;<span style="color:blue;">Read</span>&nbsp;a&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;<span style="color:blue;">ReadP</span>&nbsp;a parseRead&nbsp;=&nbsp;readPrec_to_P&nbsp;readPrec&nbsp;minPrec</pre> </p> <p> This turns every <code>Read</code> instance value into a <code>ReadP</code> value. (I admit that I wasn't sure which precedence number to use, but <code>minPrec</code> seems to work.) </p> <p> Next, you need a parser for <code>Direction</code> values: </p> <p> <pre><span style="color:#2b91af;">parseDirection</span>&nbsp;::&nbsp;<span style="color:blue;">ReadP</span>&nbsp;<span style="color:blue;">Direction</span> parseDirection&nbsp;= &nbsp;&nbsp;choice&nbsp;[ &nbsp;&nbsp;&nbsp;&nbsp;char&nbsp;<span style="color:#a31515;">&#39;N&#39;</span>&nbsp;&gt;&gt;&nbsp;<span style="color:blue;">return</span>&nbsp;North, &nbsp;&nbsp;&nbsp;&nbsp;char&nbsp;<span style="color:#a31515;">&#39;E&#39;</span>&nbsp;&gt;&gt;&nbsp;<span style="color:blue;">return</span>&nbsp;East, &nbsp;&nbsp;&nbsp;&nbsp;char&nbsp;<span style="color:#a31515;">&#39;S&#39;</span>&nbsp;&gt;&gt;&nbsp;<span style="color:blue;">return</span>&nbsp;South, &nbsp;&nbsp;&nbsp;&nbsp;char&nbsp;<span style="color:#a31515;">&#39;W&#39;</span>&nbsp;&gt;&gt;&nbsp;<span style="color:blue;">return</span>&nbsp;West&nbsp;]</pre> </p> <p> Notice how declarative this looks. The <code>choice</code> function combines a list of other parsers. When an individual parser in that list encounters the <code>'N'</code> character, it'll parse it as <code>North</code>, <code>'E'</code> as <code>East</code>, and so on. </p> <p> You can now parse an entire <code>Robot</code> using the <code>Applicative</code> <code>&lt;*&gt;</code> and <code>&lt;*</code> operators. </p> <p> <pre><span style="color:#2b91af;">parseRobot</span>&nbsp;::&nbsp;<span style="color:blue;">ReadP</span>&nbsp;<span style="color:blue;">Robot</span> parseRobot&nbsp;= &nbsp;&nbsp;(\x&nbsp;y&nbsp;d&nbsp;-&gt;&nbsp;Robot&nbsp;(x,&nbsp;y)&nbsp;d)&nbsp;&lt;$&gt; &nbsp;&nbsp;(parseRead&nbsp;&lt;*&nbsp;char&nbsp;<span style="color:#a31515;">&#39;&nbsp;&#39;</span>)&nbsp;&lt;*&gt; &nbsp;&nbsp;(parseRead&nbsp;&lt;*&nbsp;char&nbsp;<span style="color:#a31515;">&#39;&nbsp;&#39;</span>)&nbsp;&lt;*&gt; &nbsp;&nbsp;&nbsp;parseDirection</pre> </p> <p> The <code>&lt;*&gt;</code> operator combines two parsers by using the output of both of them, whereas the <code>&lt;*</code> combines two parsers by running both of them, but discarding the output of the right-hand parser. A good mnemonic is that the operator points to the parser that produces an output. Here', the <code>parseRobot</code> function uses the <code>&lt;*</code> operator to require that each number is followed by a space. The space, however, is just a delimiter, so you throw it away. </p> <p> <code>parseRead</code> parses any <code>Read</code> instance. Here, the <code>parseRobot</code> function uses it to parse each <code>Integer</code> in a robot's position. It also uses <code>parseDirection</code> to parse the robot's direction. </p> <p> Similar to how you can parse directions, you can also parse the commands: </p> <p> <pre><span style="color:#2b91af;">parseCommand</span>&nbsp;::&nbsp;<span style="color:blue;">ReadP</span>&nbsp;<span style="color:blue;">Command</span> parseCommand&nbsp;= &nbsp;&nbsp;choice&nbsp;[ &nbsp;&nbsp;&nbsp;&nbsp;char&nbsp;<span style="color:#a31515;">&#39;L&#39;</span>&nbsp;&gt;&gt;&nbsp;<span style="color:blue;">return</span>&nbsp;TurnLeft, &nbsp;&nbsp;&nbsp;&nbsp;char&nbsp;<span style="color:#a31515;">&#39;R&#39;</span>&nbsp;&gt;&gt;&nbsp;<span style="color:blue;">return</span>&nbsp;TurnRight, &nbsp;&nbsp;&nbsp;&nbsp;char&nbsp;<span style="color:#a31515;">&#39;F&#39;</span>&nbsp;&gt;&gt;&nbsp;<span style="color:blue;">return</span>&nbsp;MoveForward]</pre> </p> <p> Likewise, similar to how you parse a single robot, you can now parse a journey: </p> <p> <pre><span style="color:#2b91af;">parseJourney</span>&nbsp;::&nbsp;<span style="color:blue;">ReadP</span>&nbsp;<span style="color:blue;">Journey</span> parseJourney&nbsp;= &nbsp;&nbsp;Journey&nbsp;&lt;$&gt; &nbsp;&nbsp;(parseRobot&nbsp;&lt;*&nbsp;string&nbsp;<span style="color:#a31515;">&quot;\n&quot;</span>)&nbsp;&lt;*&gt; &nbsp;&nbsp;(many&nbsp;parseCommand&nbsp;&lt;*&nbsp;string&nbsp;<span style="color:#a31515;">&quot;\n&quot;</span>)&nbsp;&lt;*&gt; &nbsp;&nbsp;&nbsp;parseRobot</pre> </p> <p> The only new element compared to <code>parseRobot</code> is the use of the <code>many</code> parser combinator, which looks for zero, one, or many <code>Command</code> values. </p> <p> This gives you a way to parse a complete journey, but the input file contains many of those, separated by newlines and other whitespace: </p> <p> <pre><span style="color:#2b91af;">parseJourneys</span>&nbsp;::&nbsp;<span style="color:blue;">ReadP</span>&nbsp;[<span style="color:blue;">Journey</span>] parseJourneys&nbsp;=&nbsp;parseJourney&nbsp;`sepBy`&nbsp;skipSpaces</pre> </p> <p> Finally, you can parse a multi-line string into a list of journeys: </p> <p> <pre><span style="color:#2b91af;">parseInput</span>&nbsp;::&nbsp;<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;[<span style="color:blue;">Journey</span>] parseInput&nbsp;=&nbsp;<span style="color:blue;">fst</span>&nbsp;.&nbsp;minimumBy&nbsp;(comparing&nbsp;<span style="color:blue;">snd</span>)&nbsp;.&nbsp;readP_to_S&nbsp;parseJourneys</pre> </p> <p> When you run <code>readP_to_S</code>, it'll produce a list of alternatives, as there's more than one way to interpret the file according to <code>parseJourneys</code>. Each alternative is presented as a tuple of the parse result and the remaining (or unconsumed) string. I'm after the alternative that consumes as much of the input file as possible (which turns out to be all of it), so I use <code>minimumBy</code> to find the tuple that has the smallest second element. Then I return the first element of that tuple. </p> <p> Play around with <code>readP_to_S parseJourneys</code> in GHCi if you want all the details. </p> <h3 id="34135daae9634db2885e28382760d1fd"> Evaluation <a href="#34135daae9634db2885e28382760d1fd" title="permalink">#</a> </h3> <p> Haskell beginners may still find operators like <code>&lt;*&gt;</code> cryptic, but they're essential to parser combinators. Evaluation of the journeys is, in comparison, simple. </p> <p> You can start by defining a function to turn right: </p> <p> <pre><span style="color:#2b91af;">turnRight</span>&nbsp;::&nbsp;<span style="color:blue;">Robot</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Robot</span> turnRight&nbsp;r@(Robot&nbsp;_&nbsp;North)&nbsp;=&nbsp;r&nbsp;{&nbsp;robotDirection&nbsp;=&nbsp;East&nbsp;} turnRight&nbsp;r@(Robot&nbsp;_&nbsp;&nbsp;East)&nbsp;=&nbsp;r&nbsp;{&nbsp;robotDirection&nbsp;=&nbsp;South&nbsp;} turnRight&nbsp;r@(Robot&nbsp;_&nbsp;South)&nbsp;=&nbsp;r&nbsp;{&nbsp;robotDirection&nbsp;=&nbsp;West&nbsp;} turnRight&nbsp;r@(Robot&nbsp;_&nbsp;&nbsp;West)&nbsp;=&nbsp;r&nbsp;{&nbsp;robotDirection&nbsp;=&nbsp;North&nbsp;}</pre> </p> <p> There's more than one way to write a function that rotates one direction to the right, but I chose one that I found most readable. It trades clarity for verbosity by relying on simple pattern matching. I hope that it's easy to understand for Haskell beginners, and perhaps even for people who haven't seen Haskell code before. </p> <p> The function to turn left uses the same structure: </p> <p> <pre><span style="color:#2b91af;">turnLeft</span>&nbsp;::&nbsp;<span style="color:blue;">Robot</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Robot</span> turnLeft&nbsp;r@(Robot&nbsp;_&nbsp;North)&nbsp;=&nbsp;r&nbsp;{&nbsp;robotDirection&nbsp;=&nbsp;West&nbsp;} turnLeft&nbsp;r@(Robot&nbsp;_&nbsp;&nbsp;West)&nbsp;=&nbsp;r&nbsp;{&nbsp;robotDirection&nbsp;=&nbsp;South&nbsp;} turnLeft&nbsp;r@(Robot&nbsp;_&nbsp;South)&nbsp;=&nbsp;r&nbsp;{&nbsp;robotDirection&nbsp;=&nbsp;East&nbsp;} turnLeft&nbsp;r@(Robot&nbsp;_&nbsp;&nbsp;East)&nbsp;=&nbsp;r&nbsp;{&nbsp;robotDirection&nbsp;=&nbsp;North&nbsp;}</pre> </p> <p> The last command you need to implement is moving forward: </p> <p> <pre><span style="color:#2b91af;">moveForward</span>&nbsp;::&nbsp;<span style="color:blue;">Robot</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Robot</span> moveForward&nbsp;(Robot&nbsp;(x,&nbsp;y)&nbsp;North)&nbsp;=&nbsp;Robot&nbsp;(x,&nbsp;y&nbsp;+&nbsp;1)&nbsp;North moveForward&nbsp;(Robot&nbsp;(x,&nbsp;y)&nbsp;&nbsp;East)&nbsp;=&nbsp;Robot&nbsp;(x&nbsp;+&nbsp;1,&nbsp;y)&nbsp;East moveForward&nbsp;(Robot&nbsp;(x,&nbsp;y)&nbsp;South)&nbsp;=&nbsp;Robot&nbsp;(x,&nbsp;y&nbsp;-&nbsp;1)&nbsp;South moveForward&nbsp;(Robot&nbsp;(x,&nbsp;y)&nbsp;&nbsp;West)&nbsp;=&nbsp;Robot&nbsp;(x&nbsp;-&nbsp;1,&nbsp;y)&nbsp;West</pre> </p> <p> The <code>moveForward</code> function also pattern-matches on the direction the robot is facing, this time to increment or decrement the <code>x</code> or <code>y</code> coordinate as appropriate. </p> <p> You can now evaluate all three commands: </p> <p> <pre><span style="color:#2b91af;">evalCommand</span>&nbsp;::&nbsp;<span style="color:blue;">Command</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Robot</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Robot</span> evalCommand&nbsp;&nbsp;&nbsp;TurnRight&nbsp;=&nbsp;turnRight evalCommand&nbsp;&nbsp;&nbsp;&nbsp;TurnLeft&nbsp;=&nbsp;turnLeft evalCommand&nbsp;MoveForward&nbsp;=&nbsp;moveForward</pre> </p> <p> The <code>evalCommand</code> pattern-matches on all three <code>Command</code> cases and returns the appropriate function for each. </p> <p> You can now evaluate whether a <code>Journey</code> is valid: </p> <p> <pre><span style="color:#2b91af;">isJourneyValid</span>&nbsp;::&nbsp;<span style="color:blue;">Journey</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">Bool</span> isJourneyValid&nbsp;(Journey&nbsp;s&nbsp;cs&nbsp;e)&nbsp;=&nbsp;<span style="color:blue;">foldl</span>&nbsp;(<span style="color:blue;">flip</span>&nbsp;evalCommand)&nbsp;s&nbsp;cs&nbsp;==&nbsp;e</pre> </p> <p> The <code>isJourneyValid</code> function pattern-matches the constituent values out of <code>Journey</code>. I named the <code>journeyStart</code> value <code>s</code> (for <em>start</em>), the <code>journeyCommands</code> value <code>cs</code> (for <em>commands</em>), and the <code>journeyEnd</code> value <code>e</code> (for <em>end</em>). </p> <p> The <code>evalCommand</code> function evaluates a single <code>Command</code>, but a <code>Journey</code> contains many commands. You'll need to evaluate the first command to find the position from which you evaluate the second command, and so on. Imperative programmers would use a <em>for loop</em> for something like that, but in functional programming, a <em>fold</em>, in this case from the left, is how it's done. </p> <p> <code>foldl</code> requires you to supply an initial state <code>s</code> as well as the list of commands <code>cs</code>. The entire <code>foldl</code> expression produces a final <code>Robot</code> state that you can compare against the expected end state <code>e</code>. </p> <h3 id="6267cc3a03594d0fb21cd7cc61430eb0"> Execution <a href="#6267cc3a03594d0fb21cd7cc61430eb0" title="permalink">#</a> </h3> <p> Load the input file, parse it, and evaluate each journey in the <code>main</code> function: </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;">do</span> &nbsp;&nbsp;input&nbsp;&lt;-&nbsp;parseInput&nbsp;&lt;$&gt;&nbsp;<span style="color:blue;">readFile</span>&nbsp;<span style="color:#a31515;">&quot;input.txt&quot;</span> &nbsp;&nbsp;<span style="color:blue;">mapM_</span>&nbsp;<span style="color:blue;">print</span>&nbsp;$&nbsp;isJourneyValid&nbsp;&lt;$&gt;&nbsp;input</pre> </p> <p> I just load the <code>Main.hs</code> file in GHCi and run the <code>main</code> function: </p> <p> <pre>Prelude&gt; :load Main.hs [1 of 1] Compiling Main ( Main.hs, interpreted ) Ok, one module loaded. *Main&gt; main True True True</pre> </p> <p> I used the same input file as Mike Hadlow, and it turns out that all journeys are valid. That's not what I'd expected from an exercise like this, so I cloned and ran Mike's solution as well, and it seems that it arrives at the same result. </p> <h3 id="683ea9809a774338b16aed1ad41e1984"> Conclusion <a href="#683ea9809a774338b16aed1ad41e1984" title="permalink">#</a> </h3> <p> Haskell is a great language for small coding exercises that require parsing and interpretation. In this article, I demonstrated one solution to the <em>robot journeys</em> coding exercise. My goal was to show some beginner-friendly, but still idiomatic Haskell code. </p> <p> Granted, the use of parser combinators is on the verge of being overkill, but I wanted to show an example; Haskell examples are scarce, so I hope it's helpful. </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>. A red-green-refactor checklist https://blog.ploeh.dk/2019/10/21/a-red-green-refactor-checklist 2019-10-21T06:49:00+00:00 Mark Seemann <div id="post"> <p> <em>A simple read-do checklist for test-driven development.</em> </p> <p> I recently read <a href="https://amzn.to/35Wk5yD">The Checklist Manifesto</a>, a book about the power of checklists. That may sound off-putting and tedious, but I actually <a href="https://www.goodreads.com/review/show/2949987528">found it inspiring</a>. It explains how checklists empower skilled professionals to focus on difficult problems, while preventing avoidable mistakes. </p> <p> Since I read the book with the intent to see if there were ideas that we could apply in software development, I thought about checklists one might create for software development. Possibly the simplest checklist is one that describes the <em>red-green-refactor</em> cycle of test-driven development. </p> <h3 id="530e04dfea574602952023fa218d8a7c"> Types of checklists <a href="#530e04dfea574602952023fa218d8a7c" title="permalink">#</a> </h3> <p> As the book describes, there's basically two types of checklists: <ul> <li><strong>Do-confirm.</strong> With such a checklist, you perform a set of tasks, and then subsequently, at a sufficient <em>pause point</em> go through the checklist to verify that you remembered to perform all the tasks on the list.</li> <li><strong>Read-do.</strong> With this type of checklist, you read each item for instructions and then perform the task. Only when you've performed the task do you move on to the next item on the list.</li> </ul> I find it most intuitive to describe the red-green-refactor cycle as a <em>read-do</em> list. I did, however, find it expedient to include a <em>do-confirm</em> sub-list for one of the overall steps. </p> <p> This list is, I think, mostly useful if you're still learning test-driven development. It can be easily internalised. As such, I offer this for inspiration, and as a learning aid. </p> <h3 id="05b38ebc9c0c419b9a146be976578bd2"> Red-green-refactor checklist <a href="#05b38ebc9c0c419b9a146be976578bd2" title="permalink">#</a> </h3> <p> Read each of the steps in the list and perform the task. <ol> <li>Write a failing test. <ul> <li>Did you run the test?</li> <li>Did it fail?</li> <li>Did it fail because of an assertion?</li> <li>Did it fail because of the <em>last</em> assertion?</li> </ul> </li> <li>Make all tests pass by doing the simplest thing that could possibly work.</li> <li>Consider the resulting code. Can it be improved? If so, do it, but make sure that all tests still pass.</li> <li>Repeat</li> </ol> Perhaps the most value this checklist provides isn't so much the overall <em>read-do</em> list, but rather the subordinate <em>do-confirm</em> list associated with the first step. </p> <p> I regularly see people write failing tests as an initial step. The reason the test fails, however, is because the implementation throws an exception. </p> <h3 id="24a066fa0b9b401687d47b92473d63d0"> Improperly failing tests <a href="#24a066fa0b9b401687d47b92473d63d0" title="permalink">#</a> </h3> <p> Consider, as an example, the first test you might write when doing the <a href="https://en.wikipedia.org/wiki/Fizz_buzz">FizzBuzz</a> kata. </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="color:#74531f;">One</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#2b91af;">FizzBuzz</span>.<span style="color:#74531f;">Convert</span>(1); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">Equal</span>(<span style="color:#a31515;">&quot;1&quot;</span>,&nbsp;<span style="color:#1f377f;">actual</span>); }</pre> </p> <p> I wrote this test first (i.e. before the 'production' code) and used Visual Studio's refactoring tools to generate the implied type and method. </p> <p> When I run the test, it fails. </p> <p> Further investigation, however, reveals that the test fails when <code>Convert</code> is called: </p> <p> <pre>Ploeh.Katas.FizzBuzzKata.FizzBuzzTests.One Source: FizzBuzzTests.cs line: 11 Duration: 8 ms Message: System.NotImplementedException : The method or operation is not implemented. Stack Trace: at FizzBuzz.Convert(Int32 i) in FizzBuzz.cs line: 9 at FizzBuzzTests.One() in FizzBuzzTests.cs line: 13 </pre> </p> <p> This is hardly surprising, since this is the current 'implementation': </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;">Convert</span>(<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">i</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">NotImplementedException</span>(); }</pre> </p> <p> This is what the subordinate <em>do-confirm</em> checklist is for. Did the test fail because of an assertion? In this case, the answer is no. </p> <p> This means that you're not yet done with the <em>read</em> phase. </p> <h3 id="97295029364d4cd7ace15be9c9f8dc64"> Properly failing tests <a href="#97295029364d4cd7ace15be9c9f8dc64" title="permalink">#</a> </h3> <p> You can address the issue by changing the <code>Convert</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;">Convert</span>(<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">i</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; }</pre> </p> <p> This causes the test to fail because of an assertion: </p> <p> <pre> Ploeh.Katas.FizzBuzzKata.FizzBuzzTests.One Source: FizzBuzzTests.cs line: 11 Duration: 13 ms Message: Assert.Equal() Failure ↓ (pos 0) Expected: 1 Actual: ↑ (pos 0) Stack Trace: at FizzBuzzTests.One() in FizzBuzzTests.cs line: 14 </pre> </p> <p> Not only does the test fail because of an assertion - it fails because of the last assertion (since there's only one assertion). This completes the <em>do-confirm</em> checklist, and you're now ready to make the simplest change that could possibly work: </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;">Convert</span>(<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">i</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">&quot;1&quot;</span>; }</pre> </p> <p> This passes the test suite. </p> <h3 id="bdb785a78ebf475c95c64197274268c7"> Conclusion <a href="#bdb785a78ebf475c95c64197274268c7" title="permalink">#</a> </h3> <p> It's important to see tests fail. Particularly, it's important to see tests fail for the reason you expect them to fail. You'd be surprised how often you inadvertently write an <a href="/2019/10/14/tautological-assertion">assertion that can never fail</a>. </p> <p> Once you've seen the test fail for the proper reason, make it pass. </p> <p> Finally, refactor the code if necessary. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="99be0da15a164d5782afdef808300828"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> I remember the first time that I realized that I did the red step wrong because my test didn't fail for the intended reason (i.e. it didn't fail because of an assertion). Before that, I didn't realize that I needed to This is a nice programming checklist. Thanks for sharing it :) </p> <blockquote> 3. Consider the resulting code. Can it be improved? If so, do it, but make sure that all tests still pass. </blockquote> <blockquote> Finally, refactor the code if necessary. </blockquote> <p> If I can be a <a href="https://blog.ploeh.dk/2019/10/07/devils-advocate/">Devil's advocate</a> for a moment, then I would say that code can always be improved and few things are necessary. In all honesty though, I think the refactoring step is the most interesting. All three steps include aspects of science and art, but I think the refactor step includes the most of both. On the one hand, it is extremely creative and full of judgement calls about what code should be refactored and what properties the resulting code should have. On the other hand, much of the work of how to (properly) refactor is laid out in books like <a href="https://www.amazon.com/Refactoring-Improving-Existing-Addison-Wesley-Signature/dp/0134757599">Martin Fowler's Refacoring</a> and is akin to algebraic manipulations of an algebraic formula. </p> <p> In other words, I feel like there is room to expand on this checklist in the refactor step. Do you have any thoughts about you might expand it? </p> </div> <div class="comment-date">2019-10-25 00:33 UTC</div> </div> <div class="comment" id="28976782c7984115a65d539eff3d0414"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for writing. I agree that the <em>refactoring</em> step is both important and compelling. I can't, however, imagine how a checklist would be useful. </p> <p> The point of <em>The Checklist Manifesto</em> is that checklists help identify avoidable mistakes. A checklist isn't intended to describe an algorithm, but rather to make sure that crucial steps aren't forgotten. </p> <p> Another important point from <em>The Checklist Manifesto</em> is that a checklist is only effective if it's not too big. A checklist that tries to cover every eventuality isn't useful, because then people don't follow it. </p> <p> As you write, refactoring is a big topic, covered by several books. All the creativity and experience that goes into refactoring doesn't seem like something that can easily be expressed as an effective checklist. </p> <p> I don't mind being proven wrong, though, so by all means give it a go. </p> </div> <div class="comment-date">2019-10-25 21:51 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>. Tautological assertion https://blog.ploeh.dk/2019/10/14/tautological-assertion 2019-10-14T18:39:00+00:00 Mark Seemann <div id="post"> <p> <em>It's surprisingly easy to write a unit test assertion that never fails.</em> </p> <p> Recently I was mob programming with a pair of <a href="https://idq.dk">IDQ</a>'s programmers. We were starting a new code base, using test-driven development (TDD). This was the first test we wrote: </p> <p> <pre>[<span style="color:#2b91af;">Fact</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">async</span>&nbsp;<span style="color:#2b91af;">Task</span>&nbsp;<span style="font-weight:bold;color:#74531f;">HandleObserveUnitStatusStartsSaga</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">subscribers</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">List</span>&lt;<span style="color:#2b91af;">Guid</span>&gt;&nbsp;{&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">Parse</span>(<span style="color:#a31515;">&quot;{4D093799-9CCC-4135-8CB3-8661985A5853}&quot;</span>)&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">StatusPolicy</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Data&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">StatusPolicyData</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;UnitId&nbsp;=&nbsp;123, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Subscribers&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">subscribers</span> &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;">subscriber</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">Parse</span>(<span style="color:#a31515;">&quot;{003C5527-7747-4C7A-980E-67040DB738C3}&quot;</span>); &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;">ObserveUnitStatus</span>(123,&nbsp;<span style="font-weight:bold;color:#1f377f;">subscriber</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">context</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">TestableMessageHandlerContext</span>(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">await</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sut</span>.<span style="font-weight:bold;color:#74531f;">Handle</span>(<span style="font-weight:bold;color:#1f377f;">message</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">context</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">Contains</span>(<span style="font-weight:bold;color:#1f377f;">subscriber</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">sut</span>.Data.Subscribers); }</pre> </p> <p> This unit test uses <a href="https://xunit.net">xUnit.net</a> 2.4.0 and <a href="https://particular.net/nservicebus">NServiceBus</a> 7.1.10 on .NET Core 2.2. The System Under Test (SUT) is intended to be an NServiceBus Saga that monitors a resource for status changes. If a <em>unit</em> changes status, the Saga will alert its subscribers. </p> <p> The test verifies that when a new subscriber wishes to observe a unit, then its ID is added to the policy's list of subscribers. </p> <p> The test induced us to implement <code>Handle</code> like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Task</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Handle</span>(<span style="color:#2b91af;">ObserveUnitStatus</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>,&nbsp;<span style="color:#2b91af;">IMessageHandlerContext</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">context</span>) { &nbsp;&nbsp;&nbsp;&nbsp;Data.Subscribers.<span style="font-weight:bold;color:#74531f;">Add</span>(<span style="font-weight:bold;color:#1f377f;">message</span>.SubscriberId); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#2b91af;">Task</span>.CompletedTask; }</pre> </p> <p> Following the <em>red-green-refactor</em> cycle of TDD, this seemed an appropriate implementation. </p> <h3 id="8182b3c72b2940b98195f41b7a1193e8"> Enter the Devil <a href="#8182b3c72b2940b98195f41b7a1193e8" title="permalink">#</a> </h3> <p> I often use the <a href="/2019/10/07/devils-advocate">Devil's advocate</a> technique to figure out what to do next, so I made this change to the <code>Handle</code> method: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Task</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Handle</span>(<span style="color:#2b91af;">ObserveUnitStatus</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>,&nbsp;<span style="color:#2b91af;">IMessageHandlerContext</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">context</span>) { &nbsp;&nbsp;&nbsp;&nbsp;Data.Subscribers.<span style="font-weight:bold;color:#74531f;">Clear</span>(); &nbsp;&nbsp;&nbsp;&nbsp;Data.Subscribers.<span style="font-weight:bold;color:#74531f;">Add</span>(<span style="font-weight:bold;color:#1f377f;">message</span>.SubscriberId); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#2b91af;">Task</span>.CompletedTask; }</pre> </p> <p> The change is that the method first deletes all existing subscribers. This is obviously wrong, but it passes all tests. That's no surprise, since I intentionally introduced the change to make us improve the test. </p> <h3 id="55331957e1de4691bb182c2aae614f4e"> False negative <a href="#55331957e1de4691bb182c2aae614f4e" title="permalink">#</a> </h3> <p> We had to write a new test, or improve the existing test, so that the defect I just introduced would be caught. I suggested an improvement to the existing test: </p> <p> <pre>[<span style="color:#2b91af;">Fact</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">async</span>&nbsp;<span style="color:#2b91af;">Task</span>&nbsp;<span style="font-weight:bold;color:#74531f;">HandleObserveUnitStatusStartsSaga</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">subscribers</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">List</span>&lt;<span style="color:#2b91af;">Guid</span>&gt;&nbsp;{&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">Parse</span>(<span style="color:#a31515;">&quot;{4D093799-9CCC-4135-8CB3-8661985A5853}&quot;</span>)&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">StatusPolicy</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Data&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">StatusPolicyData</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;UnitId&nbsp;=&nbsp;123, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Subscribers&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">subscribers</span> &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;">subscriber</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">Parse</span>(<span style="color:#a31515;">&quot;{003C5527-7747-4C7A-980E-67040DB738C3}&quot;</span>); &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;">ObserveUnitStatus</span>(123,&nbsp;<span style="font-weight:bold;color:#1f377f;">subscriber</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">context</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">TestableMessageHandlerContext</span>(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">await</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sut</span>.<span style="font-weight:bold;color:#74531f;">Handle</span>(<span style="font-weight:bold;color:#1f377f;">message</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">context</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">Contains</span>(<span style="font-weight:bold;color:#1f377f;">subscriber</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">sut</span>.Data.Subscribers); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">Superset</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">expectedSubset</span>:&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HashSet</span>&lt;<span style="color:#2b91af;">Guid</span>&gt;(<span style="font-weight:bold;color:#1f377f;">subscribers</span>), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">actual</span>:&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HashSet</span>&lt;<span style="color:#2b91af;">Guid</span>&gt;(<span style="font-weight:bold;color:#1f377f;">sut</span>.Data.Subscribers)); }</pre> </p> <p> The only change is the addition of the last assertion. </p> <p> Smugly I asked the keyboard driver to run the tests, anticipating that it would now fail. </p> <p> It passed. </p> <p> We'd just managed to write a <a href="http://xunitpatterns.com/false%20negative.html">false negative</a>. Even though there's a defect in the code, the test still passes. I was nonplussed. None of us expected the test to pass, yet it does. </p> <p> It took us a minute to figure out what was wrong. Before you read on, try to figure it out for yourself. Perhaps it's immediately clear to you, but it took three people with decades of programming experience a few minutes to spot the problem. </p> <h3 id="6f985240963a40d8af913e251b3b86bf"> Aliasing <a href="#6f985240963a40d8af913e251b3b86bf" title="permalink">#</a> </h3> <p> The problem is <a href="https://en.wikipedia.org/wiki/Aliasing_(computing)">aliasing</a>. While named differently, <code>subscribers</code> and <code>sut.Data.Subscribers</code> is the same object. Of course one is a subset of the other, since a set is considered to be a subset of itself. </p> <p> The assertion is tautological. It can never fail. </p> <h3 id="9e8ec91f731e4f67aceefbebb76799d4"> Fixing the problem <a href="#9e8ec91f731e4f67aceefbebb76799d4" title="permalink">#</a> </h3> <p> It's surprisingly easy to write tautological assertions when working with mutable state. This regularly happens to me, perhaps a few times a month. Once you've realised that this has happened, however, it's easy to address. </p> <p> <code>subscribers</code> shouldn't change during the test, so make it immutable. </p> <p> <pre>[<span style="color:#2b91af;">Fact</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">async</span>&nbsp;<span style="color:#2b91af;">Task</span>&nbsp;<span style="font-weight:bold;color:#74531f;">HandleObserveUnitStatusStartsSaga</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Guid</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">subscribers</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">Parse</span>(<span style="color:#a31515;">&quot;{4D093799-9CCC-4135-8CB3-8661985A5853}&quot;</span>)&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">StatusPolicy</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Data&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">StatusPolicyData</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;UnitId&nbsp;=&nbsp;123, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Subscribers&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">subscribers</span>.<span style="font-weight:bold;color:#74531f;">ToList</span>() &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;">subscriber</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">Parse</span>(<span style="color:#a31515;">&quot;{003C5527-7747-4C7A-980E-67040DB738C3}&quot;</span>); &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;">ObserveUnitStatus</span>(123,&nbsp;<span style="font-weight:bold;color:#1f377f;">subscriber</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">context</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">TestableMessageHandlerContext</span>(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">await</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sut</span>.<span style="font-weight:bold;color:#74531f;">Handle</span>(<span style="font-weight:bold;color:#1f377f;">message</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">context</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">Contains</span>(<span style="font-weight:bold;color:#1f377f;">subscriber</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">sut</span>.Data.Subscribers); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">Superset</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">expectedSubset</span>:&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HashSet</span>&lt;<span style="color:#2b91af;">Guid</span>&gt;(<span style="font-weight:bold;color:#1f377f;">subscribers</span>), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">actual</span>:&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HashSet</span>&lt;<span style="color:#2b91af;">Guid</span>&gt;(<span style="font-weight:bold;color:#1f377f;">sut</span>.Data.Subscribers)); }</pre> </p> <p> An array strictly isn't immutable, but declaring it as <code>IEnumerable&lt;Guid&gt;</code> hides the mutation capabilities. The test now has to copy <code>subscribers</code> to a list before assigning it to the policy's data. This anti-aliases <code>subscribers</code> from <code>sut.Data.Subscribers</code>, and causes the test to fail. After all, there's a defect in the <code>Handle</code> method. </p> <p> You now have to remove the offending line: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Task</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Handle</span>(<span style="color:#2b91af;">ObserveUnitStatus</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>,&nbsp;<span style="color:#2b91af;">IMessageHandlerContext</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">context</span>) { &nbsp;&nbsp;&nbsp;&nbsp;Data.Subscribers.<span style="font-weight:bold;color:#74531f;">Add</span>(<span style="font-weight:bold;color:#1f377f;">message</span>.SubscriberId); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#2b91af;">Task</span>.CompletedTask; }</pre> </p> <p> This makes the test pass. </p> <h3 id="fd8e8ab5e7314ebbadc4775741af11fa"> Summary <a href="#fd8e8ab5e7314ebbadc4775741af11fa" title="permalink">#</a> </h3> <p> This article shows an example where I was surprised by aliasing. An assertion that I thought would fail turned out to be a false negative. </p> <p> You can easily make the mistake of writing a test that always passes. If you haven't tried it, you may think that you're too smart to do that, but it regularly happens to me. Other TDD practitioners have told me that it also happens to them. </p> <p> This is the reason that the <em>red-green-refactor</em> process encourages you to run each new test <em>and see it fail</em>. If you haven't seen it fail, you don't know if you've avoided a tautology. </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>. Devil's advocate https://blog.ploeh.dk/2019/10/07/devils-advocate 2019-10-07T15:00:00+00:00 Mark Seemann <div id="post"> <p> <em>How do you know when you have enough test cases. The Devil's Advocate technique can help you decide.</em> </p> <p> When I review unit tests, I often utilise a technique I call <em>Devil's Advocate</em>. I do the same whenever I consider if I have a sufficient number of test cases. The first time I explicitly named the technique was, I think, in my <a href="/outside-in-tdd">Outside-in TDD Pluralsight course</a>, in which I also discuss the so-called <em>Gollum style</em> variation. I don't think, however, that I've ever written an article explicitly about this topic. The current text attempts to rectify that omission. </p> <h3 id="a66b04a5812b4a84ba3a60a8609e58be"> Coverage <a href="#a66b04a5812b4a84ba3a60a8609e58be" title="permalink">#</a> </h3> <p> Programmers new to unit testing often struggle with identifying useful test cases. I sometimes see people writing redundant unit tests, while, on the other hand, forgetting to add important test cases. How do you know which test cases to add, and how do you know when you've added enough? </p> <p> I may return to the first question in another article, but in this, I wish to address the second question. How do you know that you have a sufficient set of test cases? </p> <p> You may think that this is a question of turning on code coverage. Surely, if you have <a href="/2015/11/16/code-coverage-is-a-useless-target-measure">100% code coverage</a>, that's sufficient? </p> <p> It's not. Consider this simple class: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">capacity</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Capacity&nbsp;=&nbsp;<span style="color:#1f377f;">capacity</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;Capacity&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="color:#74531f;">CanAccept</span>(<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="color:#1f377f;">reservation</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;=&nbsp;<span style="color:#1f377f;">reservations</span>.<span style="color:#74531f;">Sum</span>(<span style="color:#1f377f;">r</span>&nbsp;=&gt;&nbsp;<span style="color:#1f377f;">r</span>.Quantity); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">if</span>&nbsp;(Capacity&nbsp;&lt;&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;+&nbsp;<span style="color:#1f377f;">reservation</span>.Quantity) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">true</span>; &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> This class implements the (simplified) decision logic for an online restaurant reservation system. The <code>CanAccept</code> method has a cyclomatic complexity of 2, so it should be easy to cover with a pair of unit 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="color:#74531f;">CanAcceptWithNoPriorReservations</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;8,&nbsp;30), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;4 &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:#1f377f;">capacity</span>:&nbsp;10); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#1f377f;">sut</span>.<span style="color:#74531f;">CanAccept</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>[0],&nbsp;<span style="color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">True</span>(<span style="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="color:#74531f;">CanAcceptOnInsufficientCapacity</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;8,&nbsp;30), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;4 &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:#1f377f;">capacity</span>:&nbsp;10); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#1f377f;">sut</span>.<span style="color:#74531f;">CanAccept</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;7&nbsp;}&nbsp;}, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">False</span>(<span style="color:#1f377f;">actual</span>); }</pre> </p> <p> These two tests together completely cover the <code>CanAccept</code> method: </p> <p> <img src="/content/binary/coverage-of-can-accept-method.png" alt="Screen shot showing that the CanAccept method is 100% covered."> </p> <p> You'd think that this is a sufficient number of test cases of the method, then. </p> <h3 id="0ac61ef87e3f4e738475e97179242db5"> As the Devil reads the Bible <a href="#0ac61ef87e3f4e738475e97179242db5" title="permalink">#</a> </h3> <p> In Scandinavia we have an idiom that <a href="https://www.kentbeck.com">Kent Beck</a> (who's worked with Norwegian companies) has also encountered: <blockquote> <p> "TIL: "like the devil reads the Bible"--meaning someone who carefully reads a book to subvert its intent" </p> <footer><cite><a href="https://twitter.com/kentbeck/status/651817458857320449">Kent Beck</a></cite></footer> </blockquote> We have the same saying in Danish, and the Swedes also use it. </p> <p> If you think of a unit test suite as an executable specification, you may consider if you can follow the specification to the letter while intentionally introduce a defect. You can easily do that with the above <code>CanAccept</code> method: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="color:#74531f;">CanAccept</span>(<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="color:#1f377f;">reservation</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;=&nbsp;<span style="color:#1f377f;">reservations</span>.<span style="color:#74531f;">Sum</span>(<span style="color:#1f377f;">r</span>&nbsp;=&gt;&nbsp;<span style="color:#1f377f;">r</span>.Quantity); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">if</span>&nbsp;(Capacity&nbsp;&lt;=&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;+&nbsp;<span style="color:#1f377f;">reservation</span>.Quantity) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">true</span>; }</pre> </p> <p> This still passes both tests, and still has a code coverage of 100%, yet it's 'obviously' wrong. </p> <p> Can you spot the difference? </p> <p> Instead of a <em>less-than</em> comparison, it now uses a <em>less-than-or-equal</em> comparison. You could easily, inadvertently, make such a mistake while programming. It belongs in the category of <em>off-by-one errors</em>, which is one of the most common type of bugs. </p> <p> This is, in a nutshell, the Devil's Advocate technique. The intent isn't to break the software by sneaking in defects, but to explore how effectively the test suite detects bugs. In the current (simplified) example, the effectiveness of the test suite isn't impressive. </p> <h3 id="d6e4c657adec4cc1bb6d10af351a415f"> Add test cases <a href="#d6e4c657adec4cc1bb6d10af351a415f" title="permalink">#</a> </h3> <p> The problem introduced by the Devil's Advocate is an edge case. If the reservation under consideration fits the restaurant's remaining capacity, but entirely consumes it, the <code>MaîtreD</code> class should still accept it. Currently, however, it doesn't. </p> <p> It'd seem that the obvious solution is to 'fix' the 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="color:#74531f;">CanAcceptWithNoPriorReservations</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;8,&nbsp;30), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;10 &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:#1f377f;">capacity</span>:&nbsp;10); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#1f377f;">sut</span>.<span style="color:#74531f;">CanAccept</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>[0],&nbsp;<span style="color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">True</span>(<span style="color:#1f377f;">actual</span>); }</pre> </p> <p> Changing the requested <code>Quantity</code> to <code>10</code> does, indeed, cause the test to fail. </p> <h3 id="26be7b38248c4dcba5134eb4529d8214"> Beyond mutation testing <a href="#26be7b38248c4dcba5134eb4529d8214" title="permalink">#</a> </h3> <p> Until this point, you may think that the Devil's Advocate just looks like <em>an ad-hoc, informally-specified, error-prone, manual version of half of <a href="https://en.wikipedia.org/wiki/Mutation_testing">mutation testing</a></em>. So far, the change I made above could also have been made during mutation testing. </p> <p> What I sometimes do with the Devil's Advocate technique is to experiment with other, less heuristically driven changes. For instance, based on my knowledge of the existing test cases, it's not too difficult to come up with this change: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="color:#74531f;">CanAccept</span>(<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="color:#1f377f;">reservation</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;=&nbsp;<span style="color:#1f377f;">reservations</span>.<span style="color:#74531f;">Sum</span>(<span style="color:#1f377f;">r</span>&nbsp;=&gt;&nbsp;<span style="color:#1f377f;">r</span>.Quantity); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">if</span>&nbsp;(<span style="color:#1f377f;">reservation</span>.Quantity&nbsp;!=&nbsp;10) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">true</span>; }</pre> </p> <p> That's an even simpler implementation than the original, but obviously wrong. </p> <p> This should prompt you to add at least one other test case: </p> <p> <pre>[<span style="color:#2b91af;">Theory</span>] [<span style="color:#2b91af;">InlineData</span>(&nbsp;4)] [<span style="color:#2b91af;">InlineData</span>(10)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="color:#74531f;">CanAcceptWithNoPriorReservations</span>(<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">quantity</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;8,&nbsp;30), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">quantity</span> &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:#1f377f;">capacity</span>:&nbsp;10); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#1f377f;">sut</span>.<span style="color:#74531f;">CanAccept</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>[0],&nbsp;<span style="color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">True</span>(<span style="color:#1f377f;">actual</span>); }</pre> </p> <p> Notice that I converted the test to a parametrised test. This breaks the Devil's latest attempt, while the original implementation passes all tests. </p> <p> The Devil, not to be outdone, now switches tactics and goes after the <code>reservations</code> instead: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="color:#74531f;">CanAccept</span>(<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="color:#1f377f;">reservation</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;!<span style="color:#1f377f;">reservations</span>.<span style="color:#74531f;">Any</span>(); }</pre> </p> <p> This still passes all tests, including the new test case. This indicates that you'll need to add at least one test case with existing reservations, but where there's still enough capacity to accept another reservation: </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="color:#74531f;">CanAcceptWithOnePriorReservation</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;8,&nbsp;30), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;4 &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:#1f377f;">capacity</span>:&nbsp;10); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#1f377f;">sut</span>.<span style="color:#74531f;">CanAccept</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;4&nbsp;}&nbsp;}, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">True</span>(<span style="color:#1f377f;">actual</span>); }</pre> </p> <p> This new test fails, prompting you to correct the implementation of <code>CanAccept</code>. The Devil, however, can do this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="color:#74531f;">CanAccept</span>(<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="color:#1f377f;">reservation</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;=&nbsp;<span style="color:#1f377f;">reservations</span>.<span style="color:#74531f;">Sum</span>(<span style="color:#1f377f;">r</span>&nbsp;=&gt;&nbsp;<span style="color:#1f377f;">r</span>.Quantity); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;!=&nbsp;7; }</pre> </p> <p> This is still not correct, but passes all tests. It does, however, look like you're getting closer to a proper implementation. </p> <h3 id="9b955ad4a2084823a9eeb668415eb696"> Reverse Transformation Priority Premise <a href="#9b955ad4a2084823a9eeb668415eb696" title="permalink">#</a> </h3> <p> If you find this process oddly familiar, it's because it resembles the <a href="https://blog.cleancoder.com/uncle-bob/2013/05/27/TheTransformationPriorityPremise.html">Transformation Priority Premise</a> (TPP), just reversed. <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> </p> <p> When I test-drive code, I often try to follow the TPP, but when I review code with tests, the code and the tests are already in place, and it's my task to assess both. </p> <p> Applying the Devil's Advocate review technique to <code>CanAccept</code>, it seems as though I'm getting closer to a proper implementation. It does, however, require more tests. As your next move you may, for instance, consider parametrising the test case that verifies what happens when capacity is insufficient: </p> <p> <pre>[<span style="color:#2b91af;">Theory</span>] [<span style="color:#2b91af;">InlineData</span>(7)] [<span style="color:#2b91af;">InlineData</span>(8)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="color:#74531f;">CanAcceptOnInsufficientCapacity</span>(<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;8,&nbsp;30), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;4 &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:#1f377f;">capacity</span>:&nbsp;10); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#1f377f;">sut</span>.<span style="color:#74531f;">CanAccept</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;}&nbsp;}, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">False</span>(<span style="color:#1f377f;">actual</span>); }</pre> </p> <p> That doesn't help much, though, because this passes all tests: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="color:#74531f;">CanAccept</span>(<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="color:#1f377f;">reservation</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;=&nbsp;<span style="color:#1f377f;">reservations</span>.<span style="color:#74531f;">Sum</span>(<span style="color:#1f377f;">r</span>&nbsp;=&gt;&nbsp;<span style="color:#1f377f;">r</span>.Quantity); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;&lt;&nbsp;7; }</pre> </p> <p> Compared to the initial, 'desired' implementation, there's at least two issues with this code: <ul> <li>It doesn't consider <code>reservation.Quantity</code></li> <li>It doesn't take into account the <code>Capacity</code> of the restaurant</li> </ul> This indicates that you're going to have to add more test cases, varying both <code>reservation.Quantity</code> and <code>Capacity</code>. The happy-path test cases already varies <code>reservation.Quantity</code> a bit, but <code>CanAcceptOnInsufficientCapacity</code> does not, so perhaps you can follow the TPP by varying <code>reservation.Quantity</code> in that method as well: </p> <p> <pre>[<span style="color:#2b91af;">Theory</span>] [<span style="color:#2b91af;">InlineData</span>(&nbsp;1,&nbsp;10)] [<span style="color:#2b91af;">InlineData</span>(&nbsp;2,&nbsp;&nbsp;9)] [<span style="color:#2b91af;">InlineData</span>(&nbsp;3,&nbsp;&nbsp;8)] [<span style="color:#2b91af;">InlineData</span>(&nbsp;4,&nbsp;&nbsp;7)] [<span style="color:#2b91af;">InlineData</span>(&nbsp;4,&nbsp;&nbsp;8)] [<span style="color:#2b91af;">InlineData</span>(&nbsp;5,&nbsp;&nbsp;6)] [<span style="color:#2b91af;">InlineData</span>(&nbsp;6,&nbsp;&nbsp;5)] [<span style="color:#2b91af;">InlineData</span>(10,&nbsp;&nbsp;1)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="color:#74531f;">CanAcceptOnInsufficientCapacity</span>(<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">quantity</span>,&nbsp;<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;8,&nbsp;30), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">quantity</span> &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:#1f377f;">capacity</span>:&nbsp;10); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#1f377f;">sut</span>.<span style="color:#74531f;">CanAccept</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;}&nbsp;}, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">False</span>(<span style="color:#1f377f;">actual</span>); }</pre> </p> <p> This makes it harder for the Devil to come up with a malevolent implementation. Harder, but not impossible. </p> <p> It seems clear that since all test cases still use a hard-coded capacity, it ought to be possible to write an implementation that ignores the <code>Capacity</code>, but at this point I don't see a simple way to avoid looking at <code>reservation.Quantity</code>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="color:#74531f;">CanAccept</span>(<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="color:#1f377f;">reservation</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;=&nbsp;<span style="color:#1f377f;">reservations</span>.<span style="color:#74531f;">Sum</span>(<span style="color:#1f377f;">r</span>&nbsp;=&gt;&nbsp;<span style="color:#1f377f;">r</span>.Quantity); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;+&nbsp;<span style="color:#1f377f;">reservation</span>.Quantity&nbsp;&lt;&nbsp;11; }</pre> </p> <p> This implementation passes all the tests. The last batch of test cases forced the Devil to consider <code>reservation.Quantity</code>. This strongly implies that if you vary <code>Capacity</code> as well, the proper implementation out to emerge. </p> <h3 id="e3ed81c93d5847039ea53e7acd978d99"> Diminishing returns <a href="#e3ed81c93d5847039ea53e7acd978d99" title="permalink">#</a> </h3> <p> What happens, then, if you add just one test case with a different <code>Capacity</code>? </p> <p> <pre>[<span style="color:#2b91af;">Theory</span>] [<span style="color:#2b91af;">InlineData</span>(&nbsp;1,&nbsp;10,&nbsp;10)] [<span style="color:#2b91af;">InlineData</span>(&nbsp;2,&nbsp;&nbsp;9,&nbsp;10)] [<span style="color:#2b91af;">InlineData</span>(&nbsp;3,&nbsp;&nbsp;8,&nbsp;10)] [<span style="color:#2b91af;">InlineData</span>(&nbsp;4,&nbsp;&nbsp;7,&nbsp;10)] [<span style="color:#2b91af;">InlineData</span>(&nbsp;4,&nbsp;&nbsp;8,&nbsp;10)] [<span style="color:#2b91af;">InlineData</span>(&nbsp;5,&nbsp;&nbsp;6,&nbsp;10)] [<span style="color:#2b91af;">InlineData</span>(&nbsp;6,&nbsp;&nbsp;5,&nbsp;10)] [<span style="color:#2b91af;">InlineData</span>(10,&nbsp;&nbsp;1,&nbsp;10)] [<span style="color:#2b91af;">InlineData</span>(&nbsp;1,&nbsp;&nbsp;1,&nbsp;&nbsp;1)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="color:#74531f;">CanAcceptOnInsufficientCapacity</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">quantity</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">capacity</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;8,&nbsp;30), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">quantity</span> &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:#1f377f;">capacity</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#1f377f;">sut</span>.<span style="color:#74531f;">CanAccept</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;}&nbsp;}, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">False</span>(<span style="color:#1f377f;">actual</span>); }</pre> </p> <p> Notice that I just added one test case with a <code>Capacity</code> of <code>1</code>. </p> <p> You may think that this is about where the Devil ought to capitulate, but not so. This passes all tests: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="color:#74531f;">CanAccept</span>(<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="color:#1f377f;">reservation</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;=&nbsp;0; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">r</span>&nbsp;<span style="color:#8f08c4;">in</span>&nbsp;<span style="color:#1f377f;">reservations</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;=&nbsp;<span style="color:#1f377f;">r</span>.Quantity; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">break</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;+&nbsp;<span style="color:#1f377f;">reservation</span>.Quantity&nbsp;&lt;=&nbsp;Capacity; }</pre> </p> <p> Here you may feel the urge to protest. So far, all the Devil's Advocate implementations have been objectively <em>simpler</em> than the 'desired' implementation because it has involved fewer elements and has had a lower or equivalent <a href="https://en.wikipedia.org/wiki/Cyclomatic_complexity">cyclomatic complexity</a>. This new attempt to circumvent the specification seems more complex. </p> <p> It's also seems clearly ill-intentioned. Recall that the intent of the Devil's Advocate technique isn't to 'cheat' the unit tests, but rather to explore how well the test describe the desired behaviour of the system. The motivation is that it's easy to make off-by-one errors like inadvertently use <code>&lt;=</code> instead of <code>&lt;</code>. It doesn't seem quite as reasonable that a well-intentioned programmer accidentally would leave behind an implementation like the above. </p> <p> You can, however, make it <em>look</em> less complicated: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="color:#74531f;">CanAccept</span>(<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="color:#1f377f;">reservation</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;=&nbsp;<span style="color:#1f377f;">reservations</span>.<span style="color:#74531f;">Select</span>(<span style="color:#1f377f;">r</span>&nbsp;=&gt;&nbsp;<span style="color:#1f377f;">r</span>.Quantity).<span style="color:#74531f;">FirstOrDefault</span>(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;+&nbsp;<span style="color:#1f377f;">reservation</span>.Quantity&nbsp;&lt;=&nbsp;Capacity; }</pre> </p> <p> You could argue that this still looks intentionally wrong, but I've seen much code that looks like this. It seems to me that there's a kind of programmer who seems generally uncomfortable thinking in collections; they seem to subconsciously gravitate towards code that deals with singular objects. Code that attempts to get 'the' value out of a collection is, unfortunately, not that uncommon. </p> <p> Still, you might think that at this point, you've added enough test cases. That's reasonable. </p> <p> The Devil's Advocate technique isn't an <em>algorithm</em>; it has no deterministic exit criterion. It's just a heuristic that I use to explore the quality of tests. There comes a point where subjectively, I judge that the test cases <em>sufficiently</em> describe the desired behaviour. </p> <p> You may find that we've reached that point now. You could, for example, argue that in order to calculate <code>reservedSeats</code>, <code>reservations.Sum(r =&gt; r.Quantity)</code> is simpler than <code>reservations.Select(r =&gt; r.Quantity).FirstOrDefault()</code>. I'd be inclined to agree. </p> <p> There's diminishing returns to the Devil's Advocate technique. Once you find that the gains from insisting on intentionally pernicious implementations are smaller than the effort required to add more test cases, it's time to stop and commit to the test cases now in place. </p> <h3 id="609ddb35ae364efbbfb7965a646d857e"> Test case variability <a href="#609ddb35ae364efbbfb7965a646d857e" title="permalink">#</a> </h3> <p> Tests specify desired behaviour. If the tests contain less variability than the code they cover, then how can you be certain that the implementation code is correct? </p> <p> The discussion now moves into territory where I usually exercise a great deal of judgement. Read the following for inspiration, not as rigid instructions. My intent with the following is not to imply that you must always go to like extremes, but simply to demonstrate what you <em>can</em> do. Depending on circumstances (such as the cost of a defect in production), I may choose to do the following, and sometimes I may choose to skip it. </p> <p> If you consider the original implementation of <code>CanAccept</code> at the top of the article, notice that it works with <code>reservations</code> of indefinite size. If you think of <code>reservations</code> as a finite collection, it can contain zero, one, two, ten, or hundreds of elements. Yet, no test case goes beyond a single existing reservation. This is, I think, a disconnect. The tests come not even close to the degree of variability that the method can handle. If this is a piece of mission-critical software, that could be a cause for concern. </p> <p> You should add some test cases where there's two, three, or more existing reservations. People often don't do that because it seems that you'd now have to write a test method that exercises one or more test cases with two existing reservations: </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="color:#74531f;">CanAcceptWithTwoPriorReservations</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;8,&nbsp;30), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;4 &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:#1f377f;">capacity</span>:&nbsp;10); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#1f377f;">sut</span>.<span style="color:#74531f;">CanAccept</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;4&nbsp;},&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;1&nbsp;}&nbsp;}, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">True</span>(<span style="color:#1f377f;">actual</span>); }</pre> </p> <p> While this method now covers the two-existing-reservations test case, you need one to cover the three-existing-reservations test case, and so on. This seems repetitive, and probably bothers you at more than one level: <ul> <li>It's just plain tedious to have to add that kind of variability</li> <li>It seems to violate the <a href="https://en.wikipedia.org/wiki/Don%27t_repeat_yourself">DRY principle</a></li> </ul> I don't hold the DRY principle as an absolute that must always be followed, but it often indicates a maintainability problem. I think this is the case here, because the new <code>CanAcceptWithTwoPriorReservations</code> test method looks a lot like the previous <code>CanAcceptWithOnePriorReservation</code> method. If someone makes changes to the <code>MaîtreD</code> class, they would have to go and revisit all those test methods. </p> <p> What you can do instead is to parametrise the key values of the collection(s) in question. While you can't put collections of objects in <code>[InlineData]</code> attributes, you <em>can</em> put arrays of constants. For existing reservations, the key values are the quantities, so supply an array of integers as a test argument: </p> <p> <pre>[<span style="color:#2b91af;">Theory</span>] [<span style="color:#2b91af;">InlineData</span>(&nbsp;4,&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:blue;">int</span>[0])] [<span style="color:#2b91af;">InlineData</span>(10,&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:blue;">int</span>[0])] [<span style="color:#2b91af;">InlineData</span>(&nbsp;4,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;4&nbsp;})] [<span style="color:#2b91af;">InlineData</span>(&nbsp;4,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;4,&nbsp;1&nbsp;})] [<span style="color:#2b91af;">InlineData</span>(&nbsp;2,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;2,&nbsp;1,&nbsp;3,&nbsp;2&nbsp;})] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="color:#74531f;">CanAcceptWhenCapacityIsSufficient</span>(<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">quantity</span>,&nbsp;<span style="color:blue;">int</span>[]&nbsp;<span style="color:#1f377f;">reservationQantities</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;8,&nbsp;30), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">quantity</span> &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:#1f377f;">capacity</span>:&nbsp;10); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservations</span>&nbsp;=&nbsp;<span style="color:#1f377f;">reservationQantities</span>.<span style="color:#74531f;">Select</span>(<span style="color:#1f377f;">q</span>&nbsp;=&gt;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">q</span>&nbsp;}); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#1f377f;">sut</span>.<span style="color:#74531f;">CanAccept</span>(<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">True</span>(<span style="color:#1f377f;">actual</span>); }</pre> </p> <p> This single test method replaces the previous three 'happy path' test methods. The first four <code>[InlineData]</code> annotations reproduce the previous test cases, whereas the fifth <code>[InlineData]</code> annotation adds a new test case with four existing reservations. </p> <p> I gave the method a new name to better reflect the more general nature of it. </p> <p> Notice that the <code>CanAcceptWhenCapacityIsSufficient</code> method uses <code>Select</code> to turn the array of integers into a collection of <code>Reservation</code> objects. </p> <p> You may think that I cheated, since I didn't supply any other values, such as the <code>Date</code> property, to the existing reservations. This is easily addressed: </p> <p> <pre>[<span style="color:#2b91af;">Theory</span>] [<span style="color:#2b91af;">InlineData</span>(&nbsp;4,&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:blue;">int</span>[0])] [<span style="color:#2b91af;">InlineData</span>(10,&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:blue;">int</span>[0])] [<span style="color:#2b91af;">InlineData</span>(&nbsp;4,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;4&nbsp;})] [<span style="color:#2b91af;">InlineData</span>(&nbsp;4,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;4,&nbsp;1&nbsp;})] [<span style="color:#2b91af;">InlineData</span>(&nbsp;2,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;2,&nbsp;1,&nbsp;3,&nbsp;2&nbsp;})] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="color:#74531f;">CanAcceptWhenCapacityIsSufficient</span>(<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">quantity</span>,&nbsp;<span style="color:blue;">int</span>[]&nbsp;<span style="color:#1f377f;">reservationQantities</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">date</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;8,&nbsp;30); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;<span style="color:#1f377f;">date</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">quantity</span> &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:#1f377f;">capacity</span>:&nbsp;10); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservations</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#1f377f;">reservationQantities</span>.<span style="color:#74531f;">Select</span>(<span style="color:#1f377f;">q</span>&nbsp;=&gt;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">q</span>,&nbsp;Date&nbsp;=&nbsp;<span style="color:#1f377f;">date</span>&nbsp;}); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#1f377f;">sut</span>.<span style="color:#74531f;">CanAccept</span>(<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">True</span>(<span style="color:#1f377f;">actual</span>); }</pre> </p> <p> The only change compared to before is that <code>date</code> is now a variable assigned not only to <code>reservation</code>, but also to all the <code>Reservation</code> objects in <code>reservations</code>. </p> <h3 id="0564ebd7cafc44f4ba6ad017e3f0d0ce"> Towards property-based testing <a href="#0564ebd7cafc44f4ba6ad017e3f0d0ce" title="permalink">#</a> </h3> <p> Looking at a test method like <code>CanAcceptWhenCapacityIsSufficient</code> it should bother you that the <code>capacity</code> is still hard-coded. Why don't you make that a test argument as well? </p> <p> <pre>[<span style="color:#2b91af;">Theory</span>] [<span style="color:#2b91af;">InlineData</span>(10,&nbsp;&nbsp;4,&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:blue;">int</span>[0])] [<span style="color:#2b91af;">InlineData</span>(10,&nbsp;10,&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:blue;">int</span>[0])] [<span style="color:#2b91af;">InlineData</span>(10,&nbsp;&nbsp;4,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;4&nbsp;})] [<span style="color:#2b91af;">InlineData</span>(10,&nbsp;&nbsp;4,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;4,&nbsp;1&nbsp;})] [<span style="color:#2b91af;">InlineData</span>(10,&nbsp;&nbsp;2,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;2,&nbsp;1,&nbsp;3,&nbsp;2&nbsp;})] [<span style="color:#2b91af;">InlineData</span>(20,&nbsp;10,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;2,&nbsp;2,&nbsp;2,&nbsp;2&nbsp;})] [<span style="color:#2b91af;">InlineData</span>(20,&nbsp;&nbsp;4,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;2,&nbsp;2,&nbsp;4,&nbsp;1,&nbsp;3,&nbsp;3&nbsp;})] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="color:#74531f;">CanAcceptWhenCapacityIsSufficient</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">capacity</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">quantity</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>[]&nbsp;<span style="color:#1f377f;">reservationQantities</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">date</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;8,&nbsp;30); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;<span style="color:#1f377f;">date</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">quantity</span> &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:#1f377f;">capacity</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservations</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#1f377f;">reservationQantities</span>.<span style="color:#74531f;">Select</span>(<span style="color:#1f377f;">q</span>&nbsp;=&gt;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">q</span>,&nbsp;Date&nbsp;=&nbsp;<span style="color:#1f377f;">date</span>&nbsp;}); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#1f377f;">sut</span>.<span style="color:#74531f;">CanAccept</span>(<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">True</span>(<span style="color:#1f377f;">actual</span>); }</pre> </p> <p> The first five <code>[InlineData]</code> annotations just reproduce the test cases that were already present, whereas the bottom two annotations are new test cases with another <code>capacity</code>. </p> <p> How do I come up with new test cases? It's easy: In the happy-path case, the sum of existing reservation quantities, plus the requested quantity, must be less than or equal to the <code>capacity</code>. </p> <p> It sometimes helps to slightly reframe the test method. If you allow the collection of existing reservations to be the most variable element in the test method, you can express the other values relative to that input. For example, instead of supplying the <code>capacity</code> as an absolute number, you can express a test case's capacity in relation to the existing reservations: </p> <p> <pre>[<span style="color:#2b91af;">Theory</span>] [<span style="color:#2b91af;">InlineData</span>(6,&nbsp;&nbsp;4,&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:blue;">int</span>[0])] [<span style="color:#2b91af;">InlineData</span>(0,&nbsp;10,&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:blue;">int</span>[0])] [<span style="color:#2b91af;">InlineData</span>(2,&nbsp;&nbsp;4,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;4&nbsp;})] [<span style="color:#2b91af;">InlineData</span>(1,&nbsp;&nbsp;4,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;4,&nbsp;1&nbsp;})] [<span style="color:#2b91af;">InlineData</span>(0,&nbsp;&nbsp;2,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;2,&nbsp;1,&nbsp;3,&nbsp;2&nbsp;})] [<span style="color:#2b91af;">InlineData</span>(2,&nbsp;10,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;2,&nbsp;2,&nbsp;2,&nbsp;2&nbsp;})] [<span style="color:#2b91af;">InlineData</span>(1,&nbsp;&nbsp;4,&nbsp;<span style="color:blue;">new</span>[]&nbsp;{&nbsp;2,&nbsp;2,&nbsp;4,&nbsp;1,&nbsp;3,&nbsp;3&nbsp;})] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="color:#74531f;">CanAcceptWhenCapacityIsSufficient</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">capacitySurplus</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>&nbsp;<span style="color:#1f377f;">quantity</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>[]&nbsp;<span style="color:#1f377f;">reservationQantities</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">date</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;8,&nbsp;30); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;<span style="color:#1f377f;">date</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">quantity</span> &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;=&nbsp;<span style="color:#1f377f;">reservationQantities</span>.<span style="color:#74531f;">Sum</span>(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">capacity</span>&nbsp;=&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;+&nbsp;<span style="color:#1f377f;">quantity</span>&nbsp;+&nbsp;<span style="color:#1f377f;">capacitySurplus</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:#1f377f;">capacity</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservations</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#1f377f;">reservationQantities</span>.<span style="color:#74531f;">Select</span>(<span style="color:#1f377f;">q</span>&nbsp;=&gt;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">q</span>,&nbsp;Date&nbsp;=&nbsp;<span style="color:#1f377f;">date</span>&nbsp;}); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#1f377f;">sut</span>.<span style="color:#74531f;">CanAccept</span>(<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">True</span>(<span style="color:#1f377f;">actual</span>); }</pre> </p> <p> Notice that the value supplied as a test argument is now named <code>capacitySurplus</code>. This represents the surplus capacity for each test case. For example, in the first test case, the <code>capacity</code> was previously supplied as the absolute number <code>10</code>. The requested quantity is <code>4</code>, and since there's no prior reservations in that test case, the capacity surplus, after accepting the reservation, is <code>6</code>. </p> <p> Likewise, in the second test case, the requested quantity is <code>10</code>, and since the absolute capacity is also <code>10</code>, when you reframe the test case, the surplus capacity, after accepting the reservation, is <code>0</code>. </p> <p> This seems odd if you aren't used to it. You'd probably intuitively think of a restaurant's <code>Capacity</code> as 'the most absolute' number, in that it's often a number that originates from physical constraints. </p> <p> When you're looking for test cases, however, you aren't looking for test cases for a particular restaurant. You're looking for test cases for an arbitrary restaurant. In other words, you're looking for test inputs that belong to the same <em>equivalence class</em>. </p> <h3 id="174e2338027e4f3ca0b84dd0fb6adc5f"> Property-based testing <a href="#174e2338027e4f3ca0b84dd0fb6adc5f" title="permalink">#</a> </h3> <p> I haven't explicitly stated this yet, but both the <code>capacity</code> and each reservation <code>Quantity</code> should be a positive number. This should really have been <a href="/2015/01/19/from-primitive-obsession-to-domain-modelling">captured as a proper domain object</a>, but I chose to keep these values as primitive integers in order to not complicate the example too much. </p> <p> If you look at the test parameters for the latest incarnation of <code>CanAcceptWhenCapacityIsSufficient</code>, you may now observe the following: <ul> <li><code>capacitySurplus</code> can be an arbitrary non-negative number</li> <li><code>quantity</code> can be an arbitrary positive number</li> <li><code>reservationQantities</code> can be an arbitrary array of positive numbers, including the empty array</li> </ul> This isn't too hard to express with, say, <a href="https://fscheck.github.io/FsCheck">FsCheck</a> (2.14.0): </p> <p> <pre>[<span style="color:#2b91af;">Property</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="color:#74531f;">CanAcceptWhenCapacityIsSufficient</span>( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">NonNegativeInt</span>&nbsp;<span style="color:#1f377f;">capacitySurplus</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">PositiveInt</span>&nbsp;<span style="color:#1f377f;">quantity</span>, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">PositiveInt</span>[]&nbsp;<span style="color:#1f377f;">reservationQantities</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">date</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">DateTime</span>(2018,&nbsp;8,&nbsp;30); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Date&nbsp;=&nbsp;<span style="color:#1f377f;">date</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">quantity</span>.Item &nbsp;&nbsp;&nbsp;&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;=&nbsp;<span style="color:#1f377f;">reservationQantities</span>.<span style="color:#74531f;">Sum</span>(<span style="color:#1f377f;">x</span>&nbsp;=&gt;&nbsp;<span style="color:#1f377f;">x</span>.Item); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">capacity</span>&nbsp;=&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;+&nbsp;<span style="color:#1f377f;">quantity</span>.Item&nbsp;+&nbsp;<span style="color:#1f377f;">capacitySurplus</span>.Item; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">sut</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>(<span style="color:#1f377f;">capacity</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservations</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#1f377f;">reservationQantities</span>.<span style="color:#74531f;">Select</span>(<span style="color:#1f377f;">q</span>&nbsp;=&gt;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;{&nbsp;Quantity&nbsp;=&nbsp;<span style="color:#1f377f;">q</span>.Item,&nbsp;Date&nbsp;=&nbsp;<span style="color:#1f377f;">date</span>&nbsp;}); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#1f377f;">sut</span>.<span style="color:#74531f;">CanAccept</span>(<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">True</span>(<span style="color:#1f377f;">actual</span>); }</pre> </p> <p> This refactoring takes advantage of FsCheck's built-in wrapper types <code>NonNegativeInt</code> and <code>PositiveInt</code>. If you'd like an introduction to FsCheck, you could watch my <a href="/property-based-testing-intro">Introduction to Property-based Testing with F#</a> Pluralsight course. </p> <p> By default, FsCheck runs each property 100 times, so now, instead of seven test cases, you now have 100. </p> <h3 id="1eddf5bb91324b18880c78d1f1825ea6"> Limits to the Devil's Advocate technique <a href="#1eddf5bb91324b18880c78d1f1825ea6" title="permalink">#</a> </h3> <p> There's a limit to the Devil's Advocate technique. Unless you're working with <a href="/2015/02/23/property-based-testing-without-a-property-based-testing-framework">a problem where you can exhaust the entire domain of possible test cases</a>, your testing strategy is always going to be a sampling strategy. You run your automated tests with either hard-coded values or randomly generated values, but regardless, a test run isn't going to cover all possible input combinations. </p> <p> For example, a truly hostile Devil could make this change to the <code>CanAccept</code> method: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="color:#74531f;">CanAccept</span>(<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&nbsp;<span style="color:#1f377f;">reservations</span>,&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="color:#1f377f;">reservation</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">if</span>&nbsp;(<span style="color:#1f377f;">reservation</span>.Quantity&nbsp;==&nbsp;3953911) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">true</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;=&nbsp;<span style="color:#1f377f;">reservations</span>.<span style="color:#74531f;">Sum</span>(<span style="color:#1f377f;">r</span>&nbsp;=&gt;&nbsp;<span style="color:#1f377f;">r</span>.Quantity); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#8f08c4;">return</span>&nbsp;<span style="color:#1f377f;">reservedSeats</span>&nbsp;+&nbsp;<span style="color:#1f377f;">reservation</span>.Quantity&nbsp;&lt;=&nbsp;Capacity; }</pre> </p> <p> Even if you increase the number of test cases that FsCheck generates to, say, 100,000, it's unlikely to find the poisonous branch. The chance of randomly generating a <code>quantity</code> of <em>exactly</em> <code>3953911</code> isn't that great. </p> <p> The Devil's Advocate technique doesn't guarantee that you'll have enough test cases to protect yourself against all sorts of odd defects. It does, however, still work well as an analysis tool to figure out if there's 'enough' test cases. </p> <h3 id="6ad7a48fd0c04f91af236d99f0722617"> Conclusion <a href="#6ad7a48fd0c04f91af236d99f0722617" title="permalink">#</a> </h3> <p> The Devil's Advocate technique is a heuristic you can use to evaluate whether more test cases would improve confidence in the test suite. You can use it to review existing (test) code, but you can also use it as inspiration for new test cases that you should consider adding. </p> <p> The technique is to deliberately implement the system under test incorrectly. The more incorrect you can make it, the more test cases you'll be likely to have to add. </p> <p> When there's only a few test cases, you can probably get away with a decidedly unsound implementation that still passes all tests. These are often simpler than the 'intended' implementation. In this phase of applying the heuristic, this clearly demonstrates the need for more test cases. </p> <p> At a later stage, you'll have to go deliberately out of your way to produce a wrong implementation that still passes all tests. When that happens, it may be time to stop. </p> <p> The intent of the technique is to uncover how many test cases you need to protect against common defects in the future. Thus, it's not a measure of <em>current</em> code coverage. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="fd53c72c360b42999b87c87649460e78"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> <p> When there's only a few test cases, you can probably get away with a decidedly unsound implementation that still passes all tests. These are often simpler than the 'intended' implementation. In this phase of applying the heuristic, this clearly demonstrates the need for more test cases. </p> <p> At a later stage, you'll have to go deliberately out of your way to produce a wrong implementation that still passes all tests. When that happens, it may be time to stop. </p> </blockquote> <p> I like to think of this behavior as a phrase transition. </p> <blockquote> Unless you're working with a problem where you can exhaust the entire domain of possible test cases, your testing strategy is always going to be a sampling strategy. </blockquote> <p> I agree with this in practice, but it is not always true in theory. A counter eaxample is <a href="https://en.wikipedia.org/wiki/Polynomial_interpolation">polynomial interpolation</a>. </p> <p> Normally we think of a polynomial in an indeterminate <code>x</code> of degree <code>n</code> as being specified by a list of <code>n + 1</code> coefficients, where the <code>i</code>th coefficient is the coefficient of <code>x<sup>i</sup></code>. Evaluating this polynomial given a value for <code>x</code> is easy; it just involves exponentiation, multiplication, and addition. Polynomial evaluation has a conceptual inverse called polynomial interpolation. In this direction, the input is evaluations at <code>n + 1</code> points in "general position" and the output is the <code>n + 1</code> coefficients. For example, a line is a polynomial of degree <code>1</code> and two points are in general position if they are not the same point. This is commonly expressed the phrase "Any two (distinct) points defines a line." Three points are in general position if they are not co-linear, where co-linear means that all three points are on the same line. In general, <code>n + 1</code> points are in general position if they are not all on the same polynomial of degree <code>n</code>. <p> <p> Anyway, here is the point. If a pure function is known to implement some polynomial of degree (at most) <code>n</code>, then even if the domain is infinite, there exists <code>n + 1</code> inputs such that it is sufficient to test this function for correctness on those inputs. </p> <p> This is why I think the phrase transition in the Devil's advocate testing is critical. There is some objective measure of complexity of the function under test (such as cyclomatic complexity), and we have an intuitive sense that a certain number of tests is sufficient for testing functions with that complexity. If the Devil is allowed to add monomials to the polynomial (or, heaven forbid, modify the implementation so that it is not a polynomial), then any finite number of tests can be circumvented. If instead the Devil is only allowed to modify the coefficients of the polynomial, then we have a winning strategy. </p> <blockquote> Here you may feel the urge to protest. So far, all the Devil's Advocate implementations have been objectively simpler than the 'desired' implementation because it has involved fewer elements and has had a lower or equivalent cyclomatic complexity. This new attempt to circumvent the specification seems more complex. </blockquote> <p> I think it would be exceedingly intersting if you can formally define what you mean here by "objectively". In the case of a polynomial (and speaking slightly roughly), changing the "first" nonzero coefficient to <code>0</code> decreases the complexity (i.e. the degree of the polynomial) while any other change to that coefficient or any change to any other coefficient maintains the complexity. </p> </div> <div class="comment-date">2019-10-25 01:32 UTC</div> </div> <div class="comment" id="cb15452b8c96429998efd50b67373da3"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for writing. What I meant by <em>objectively simpler</em> I partially explain in the same paragraph. I consider cyclomatic complexity one of hardly any useful measurements in software development. As I also imply in the article, I consider Robert C. Martin's <em>Transformation Priority Premise</em> to include a good ranking of code constructs, e.g. that using a constant is simpler than using a variable, and so on. </p> <p> I don't think you need to reach for polynomial interpolation in order to make your point. Just consider a function that returns a constant value, like this one: </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;">Foo</span>(<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">i</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">&quot;foo&quot;</span>; }</pre> </p> <p> You can make a similar argument about this function: You only need a single test value in order to demonstrate that it works as intended. I suppose you could view that as a zero-degree polynomial. </p> <p> Beyond what you think of as the <em>phase transition</em> I sometimes try to see what happens if I slightly <em>increase</em> the complexity of a function. For the <code>Foo</code> function, it could be a change like this: </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;">Foo</span>(<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">i</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">i</span>&nbsp;&lt;&nbsp;-1000) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</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:#a31515;">&quot;foo&quot;</span>; }</pre> </p> <p> Unless you just happened to pick a number less than <code>-1000</code> for your test value, your test will not discover such a change. </p> <p> Your argument attempts to guard against that sort of change by assuming that we can somehow 'forbid' a change from a polynomial to something irregular. Real code doesn't work that way. Real code is rarely a continuous function, but rather discrete. That's the reason we have a concept such as <em>edge case</em>, because code branches at discrete values. </p> <p> A polynomial is a single function, regardless of degree. Implemented in code, it'll have a cyclomatic complexity of 1. That may not even be worth testing, because you'd essentially only be reproducing the implementation code in your test. </p> <p> The purpose of the Devil's Advocate technique isn't to demonstrate correctness; that's what unit tests are for. The purpose of the Devil's Advocate technique is to critique the tests. </p> <p> In reality, I never imagine that some malicious developer gains access to the source code. On the other hand, we all make mistakes, and I try to imagine what a likely mistake might look like. </p> </div> <div class="comment-date">2019-10-26 3:57 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>. 10x developers https://blog.ploeh.dk/2019/09/30/10x-developers 2019-09-30T06:56:00+00:00 Mark Seemann <div id="post"> <p> <em>Do 10x developers exist? I believe that they do, but not like you may think.</em> </p> <p> The notion that some software developers are ten times (10x) as productive as 'normal' developers is decades old. Once in a while, the discussion resurfaces. It's a controversial subject, but something I've been thinking about for years, so I thought that I'd share my perspective because I don't see anyone else arguing from this position. </p> <p> While I'll try to explain my reasoning, I'll make no attempt at passing this off as anything but my current, subjective viewpoint. Please leave a comment if you have something to add. </p> <h3 id="11f6ec960f694758892bff549eb79d59"> Perspective <a href="#11f6ec960f694758892bff549eb79d59" title="permalink">#</a> </h3> <p> Meet Yohan. You've probably had a colleague like him. He's one of those software developers who gets things done, who never says no when the business asks him to help them out, who always respond with a smile to any request. </p> <p> I've had a few colleagues like Yohan in my career. It can be enlightening overhearing non-technical stakeholders discuss software developers: </p> <p> <strong>Alice:</strong> Yohan is such a dear; he helped me out with that feature on the web site, you know... </p> <p> <strong>Bob:</strong> Yes, he's a real go-getter. All the other programmers just say no and look pissed when I approach them about anything. </p> <p> <strong>Alice:</strong> Yohan always says yes, and he gets things done. He's a real 10x developer. </p> <p> <strong>Bob:</strong> We're so lucky we have him... </p> <p> Overhearing such a conversation can be frustrating. Yohan is your colleague, and you've just about had enough of him. Yohan is one of those developers who'll surround all code with a <code>try-catch</code> block, because then there'll be no exceptions in production. Yohan will make changes directly to the production system and tell no-one. Yohan will copy and paste code. Yohan will put business logic in database triggers, or rewrite logs, or use email as a messaging system, or call, parse, and run HTML-embedded JavaScript code on back-end servers. All 'because it's faster and provides more business value.' </p> <p> Yohan is a 10x developer. </p> <p> You, and the rest of your team, get nothing done. </p> <p> You get nothing done because you waste all your time cleaning up the trail of garbage and technical debt Yohan leaves in his wake. </p> <p> Business stakeholders may view Yohan as being orders of magnitude more productive than other developers, because most programming work is invisible and intangible. Whether or not someone is a 10x developer is highly subjective, and depends on perspective. </p> <h3 id="57c36b775bca4e848cadf50182028191"> Context <a href="#57c36b775bca4e848cadf50182028191" title="permalink">#</a> </h3> <p> The notion that some people are orders of magnitude more productive than the 'baseline' programmer has other problems. It implicitly assumes that a 'baseline' programmer exists in the first place. Modern software development, however, is specialised. </p> <p> As an example, I've been doing test-driven, ASP.NET-based C# server-side enterprise development for decades. Drop me into a project with my favourite stack and watch me go. On the other hand, try asking me to develop a game for the Sony PlayStation, and watch me stall. </p> <p> Clearly, then, I'm a 10x developer, for the tautological reason that I'm much better at the things that I'm good at than the things I'm not good at. </p> <p> Even the greatest <a href="https://en.wikipedia.org/wiki/R_(programming_language)">R</a> developer is unlikely to be of much help on your next <a href="https://en.wikipedia.org/wiki/COBOL">COBOL</a> project. </p> <p> As always, context matters. You can be a great programmer in a particular context, and suck in another. </p> <p> This isn't limited to technology stacks. Some people prefer co-location, while others work best by themselves. Some people are detail-oriented, while others like to look at the big picture. Some people do their best work early in the morning, and others late at night. </p> <p> And some teams of 'mediocre' programmers outperform all-star teams. (This, incidentally, is a phenomenon also <a href="https://en.wikipedia.org/wiki/UEFA_Euro_1992">sometimes seen</a> in professional <a href="https://en.wikipedia.org/wiki/Association_football">Soccer</a>.) </p> <h3 id="34e113a19c8040b0bcb38f7abf1b532d"> Evidence <a href="#34e113a19c8040b0bcb38f7abf1b532d" title="permalink">#</a> </h3> <p> Unfortunately, as I explain in my <a href="https://cleancoders.com/video-details/humane-code-real-episode-1">Humane Code</a> video, I believe that you can't measure software development productivity. Thus, the notion of a 10x developer is subjective. </p> <p> The original idea, however, is decades old, and seems, at first glance, to originate in a 'study'. If you're curious about its origins, I can't recommend <a href="http://bit.ly/leprechauns-of-software-engineering">The Leprechauns of Software Engineering</a> enough. In that book, Laurent Bossavit explains just how insubstantial the evidence is. </p> <p> If the evidence is so weak, then why does the idea that 10x developers exist keep coming back? </p> <h3 id="6988798f60bf4622808b58a3e7f55bce"> 0x developers <a href="#6988798f60bf4622808b58a3e7f55bce" title="permalink">#</a> </h3> <p> I think that the reason that the belief is recurring is that (subjectively) <em>it seems so evident</em>. Barring confirmation bias, I'm sure everyone has encountered a team member that never seemed to get anything done. </p> <p> I know that I've certainly had that experience from time to time. </p> <p> The first job I had, I hated. I just couldn't muster any enthusiasm for the work, and I'd postpone and drag out as long as possible even the simplest task. That wasn't very mature, but I was 25 and it was my first job, and I didn't know how to handle the situation I found myself in. I'm sure that my colleagues back then found that I didn't pull my part. I didn't, and I'm not proud of it, but it's true. </p> <p> I believe now that I was in the wrong context. It wasn't that I was incapable of doing the job, but at that time in my career, I absolutely loathed it, and for that reason, I wasn't productive. </p> <p> Another time, I had a colleague who seemed incapable of producing anything that helped us achieve our goals. I was concerned that I'd <a href="https://en.wikipedia.org/wiki/Bozo_bit">flipped the bozo bit</a> on that colleague, so I started to collect evidence. Our Git repository had few commits from that colleague, and the few that I could find I knew had been made in collaboration with another team member. We shared an office, and I had a pretty good idea about who worked together with whom when. </p> <p> This colleague spent a lot of time talking to other people. Us, other stakeholders, or any hapless victim who didn't escape in time. Based on these meetings and discussions, we'd hear about all sorts of ideas for improvements for our code or development process, but nothing would be implemented, and rarely did it have any relevance to what we were trying to accomplish. </p> <p> I've met programmers who get nothing done more than once. Sometimes, like the above story, they're boisterous bluffs, but most often, they just sit quietly in their corner and fidget with who knows what. </p> <p> Based on the above, mind you, I'm not saying that these people are necessarily incompetent (although I suspect that some are). They might also just find themselves in a wrong context, like I did in my first job. </p> <p> It seems clear to me, then, that there's such a thing as a <em>0x developer</em>. This is a developer who gets zero times (0x) as much done as the 'average' developer. </p> <p> For that reason it seems evident to me that 10x developers exist. Any developer who regularly manages to get code deployed to production is not only ten times, but infinitely more productive than 0x developers. </p> <p> It gets worse, though. </p> <h3 id="fe07476743704027acab9c7b949bc3a4"> −nx developers <a href="#fe07476743704027acab9c7b949bc3a4" title="permalink">#</a> </h3> <p> Not only is it my experience that 0x developers exist, I also believe that I've met more than one <em>−nx developer</em>. These are developers who are <em>minus n times</em> 'more' productive than the 'baseline' developer. In other words, they are software developers who have negative productivity. </p> <p> I've never met anyone who I suspected of deliberately sabotaging our efforts; they always seem well-meaning, but some people can produce more mess than three colleagues can clean up. Yohan, above, is such an archetype. </p> <p> One colleague I had, long ago, was so bad that the rest of the team deliberately compartmentalised him/her. We'd ask him/her to work on an isolated piece of the system, knowing that (s)he would be assigned to another project after four months. We then secretly planned to throw away the code once (s)he was gone, and rewrite it. I don't know if that was the right decision, but since we had padded all other estimates accordingly, we made our deadlines without more than the usual overruns. </p> <p> If you accept the assertion that −nx developers exist, then clearly, anyone who gets anything done at all is an <em>∞x developer</em>. </p> <h3 id="8257729b743641d0afa1c2ddbfe1b0df"> Summary <a href="#8257729b743641d0afa1c2ddbfe1b0df" title="permalink">#</a> </h3> <p> 10x developers exist, but not in the way that people normally interpret the term. </p> <p> 10x developers exist because there's great variability in (perceived) productivity. Much of the variability is context-dependent, so it's less clear if some people are just 'better at programming' than others. Still, when we consider that people like <a href="https://en.wikipedia.org/wiki/Linus_Torvalds">Linus Torvalds</a> exist, it seems compelling that this might be the case. </p> <p> Most of the variability, however, I think correlates with environment. Are you working in a technology stack with which you're comfortable? Do you like what you're doing? Do you like your colleagues? Do you like your hours? Do you like your working environment? </p> <p> Still, even if we could control for all of those variables, we might still find that some people get stuff done, and some people don't. The people who get anything done are ∞x developers. </p> <p> Employers and non-technical start-up founders sometimes look for the 10x unicorns, just like they look for <em>rock star developers</em>. <blockquote> <p> "To really confuse recruiters, someone should make a programming language called Rockstar." </p> <footer><cite><a href="https://twitter.com/paulstovell/status/1013960369465782273">Paul Stovell</a></cite></footer> </blockquote> The above tweet inspired <a href="http://www.dylanbeattie.net">Dylan Beattie</a> to create <a href="https://codewithrockstar.com">the Rockstar programming language</a>. </p> <p> Perhaps we should also create a <em>10x</em> programming language, so that we could put <em>certified Rockstar programmer, 10x developer</em> on our resumes. </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>. Unit testing wai applications https://blog.ploeh.dk/2019/09/23/unit-testing-wai-applications 2019-09-23T06:35:00+00:00 Mark Seemann <div id="post"> <p> <em>One way to unit test a wai application with the API provided by Network.Wai.Test.</em> </p> <p> I'm currently developing a REST API in <a href="https://www.haskell.org">Haskell</a> using <a href="https://haskell-servant.readthedocs.io">Servant</a>, and I'd like to test the HTTP API as well as the functions that I use to compose it. The Servant documentation, as well as the <em>servant</em> <a href="https://haskellstack.org">Stack</a> template, uses <a href="http://hackage.haskell.org/package/hspec">hspec</a> to drive the tests. </p> <p> I tried to develop my code with hspec, but I found it confusing and inflexible. It's possible that I only found it inflexible because I didn't understand it well enough, but I don't think you can argue with my experience of finding it confusing. </p> <p> I prefer a combination of <a href="https://hackage.haskell.org/package/HUnit">HUnit</a> and <a href="http://hackage.haskell.org/package/QuickCheck">QuickCheck</a>. It turns out that it's possible to test a <a href="http://hackage.haskell.org/package/wai">wai</a> application (including Servant) using only those test libraries. </p> <h3 id="1c7a7365bd0c425e85691625d00adcd0"> Testable HTTP requests <a href="#1c7a7365bd0c425e85691625d00adcd0" title="permalink">#</a> </h3> <p> When testing against the HTTP API itself, you want something that can simulate the HTTP traffic. That capability is provided by <a href="http://hackage.haskell.org/package/wai-extra/docs/Network-Wai-Test.html">Network.Wai.Test</a>. At first, however, it wasn't entirely clear to me how that library works, but I could see that the Servant-recommended <a href="http://hackage.haskell.org/package/hspec-wai/docs/Test-Hspec-Wai.html">Test.Hspec.Wai</a> is just a thin wrapper over <em>Network.Wai.Test</em> (notice how <a href="/2019/07/01/yes-silver-bullet">open source makes such research much easier</a>). </p> <p> It turns out that <em>Network.Wai.Test</em> enables you to run your tests in a <code>Session</code> monad. You can, for example, define a simple HTTP GET request like this: </p> <p> <pre><span style="color:blue;">import</span>&nbsp;<span style="color:blue;">qualified</span>&nbsp;Data.ByteString&nbsp;<span style="color:blue;">as</span>&nbsp;BS <span style="color:blue;">import</span>&nbsp;<span style="color:blue;">qualified</span>&nbsp;Data.ByteString.Lazy&nbsp;<span style="color:blue;">as</span>&nbsp;LBS <span style="color:blue;">import</span>&nbsp;Network.HTTP.Types <span style="color:blue;">import</span>&nbsp;Network.Wai <span style="color:blue;">import</span>&nbsp;Network.Wai.Test <span style="color:#2b91af;">get</span>&nbsp;::&nbsp;<span style="color:blue;">BS</span>.<span style="color:blue;">ByteString</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Session</span>&nbsp;<span style="color:blue;">SResponse</span> get&nbsp;url&nbsp;=&nbsp;request&nbsp;$&nbsp;setPath&nbsp;defaultRequest&nbsp;{&nbsp;requestMethod&nbsp;=&nbsp;methodGet&nbsp;}&nbsp;url </pre> </p> <p> This <code>get</code> function takes a <code>url</code> and returns a <code>Session SResponse</code>. It uses the <code>defaultRequest</code>, so it doesn't set any specific HTTP headers. </p> <p> For HTTP POST requests, I needed a function that'd POST a JSON document to a particular URL. For that purpose, I had to do a little more work: </p> <p> <pre><span style="color:#2b91af;">postJSON</span>&nbsp;::&nbsp;<span style="color:blue;">BS</span>.<span style="color:blue;">ByteString</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">LBS</span>.<span style="color:blue;">ByteString</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Session</span>&nbsp;<span style="color:blue;">SResponse</span> postJSON&nbsp;url&nbsp;json&nbsp;=&nbsp;srequest&nbsp;$&nbsp;SRequest&nbsp;req&nbsp;json &nbsp;&nbsp;<span style="color:blue;">where</span> &nbsp;&nbsp;&nbsp;&nbsp;req&nbsp;=&nbsp;setPath&nbsp;defaultRequest &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;requestMethod&nbsp;=&nbsp;methodPost &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;,&nbsp;requestHeaders&nbsp;=&nbsp;[(hContentType,&nbsp;<span style="color:#a31515;">&quot;application/json&quot;</span>)]}&nbsp;url</pre> </p> <p> This is a little more involved than the <code>get</code> function, because it also has to supply the <code>Content-Type</code> HTTP header. If you don't supply that header with the <code>application/json</code> value, your API is going to reject the request when you attempt to post a string with a JSON object. </p> <p> Apart from that, it works the same way as the <code>get</code> function. </p> <h3 id="d726d432f53b4817b5dc9716a2fabc36"> Running a test session <a href="#d726d432f53b4817b5dc9716a2fabc36" title="permalink">#</a> </h3> <p> The <code>get</code> and <code>postJSON</code> functions both return <code>Session</code> values, so a test must run in the <code>Session</code> monad. This is easily done with Haskell's <code>do</code> notation; you'll see an example of that later in the article. </p> <p> First, however, you'll need a way to run a <code>Session</code>. <em>Network.Wai.Test</em> provides a function for that, called <code>runSession</code>. Besides a <code>Session a</code> value, though, it also requires an <code>Application</code> value. </p> <p> In my test library, I already have an <code>Application</code>, although it's running in <code>IO</code> (for reasons that'll take another article to explain): </p> <p> <pre><span style="color:#2b91af;">app</span>&nbsp;::&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;<span style="color:blue;">Application</span></pre> </p> <p> With this value, you can easily convert any <code>Session a</code> to <code>IO a</code>: </p> <p> <pre><span style="color:#2b91af;">runSessionWithApp</span>&nbsp;::&nbsp;<span style="color:blue;">Session</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;a runSessionWithApp&nbsp;s&nbsp;=&nbsp;app&nbsp;&gt;&gt;=&nbsp;runSession&nbsp;s</pre> </p> <p> The next step is to figure out how to turn an <code>IO a</code> into a test. </p> <h3 id="febab39aa10d4d78bfd0bc4d3d45ca8a"> Running a property <a href="#febab39aa10d4d78bfd0bc4d3d45ca8a" title="permalink">#</a> </h3> <p> You can turn an <code>IO a</code> into a <code>Property</code> with either <code>ioProperty</code> or <code>idempotentIOProperty</code>. I admit that the documentation doesn't make the distinction between the two entirely clear, but <code>ioProperty</code> sounds like the safer choice, so that's what I went for here. </p> <p> With <code>ioProperty</code> you now have a <code>Property</code> that you can turn into a <code>Test</code> using <code>testProperty</code> from <a href="http://hackage.haskell.org/package/test-framework-quickcheck2/docs/Test-Framework-Providers-QuickCheck2.html">Test.Framework.Providers.QuickCheck2</a>: </p> <p> <pre><span style="color:#2b91af;">appProperty</span>&nbsp;::&nbsp;(<span style="color:blue;">Functor</span>&nbsp;f,&nbsp;<span style="color:blue;">Testable</span>&nbsp;prop,&nbsp;<span style="color:blue;">Testable</span>&nbsp;(f&nbsp;<span style="color:blue;">Property</span>)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=&gt;&nbsp;TestName&nbsp;-&gt;&nbsp;f&nbsp;(Session&nbsp;prop)&nbsp;-&gt;&nbsp;Test appProperty&nbsp;name&nbsp;= &nbsp;&nbsp;testProperty&nbsp;name&nbsp;.&nbsp;<span style="color:blue;">fmap</span>&nbsp;(ioProperty&nbsp;.&nbsp;runSessionWithApp)</pre> </p> <p> The type of this function seems more cryptic than strictly necessary. What's that <code>Functor f</code> doing there? </p> <p> The way I've written the tests, each property receives input from QuickCheck in the form of function arguments. I could have given the <code>appProperty</code> function a more restricted type, to make it clearer what's going on: </p> <p> <pre><span style="color:#2b91af;">appProperty</span>&nbsp;::&nbsp;(<span style="color:blue;">Arbitrary</span>&nbsp;a,&nbsp;<span style="color:blue;">Show</span>&nbsp;a,&nbsp;<span style="color:blue;">Testable</span>&nbsp;prop) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=&gt;&nbsp;TestName&nbsp;-&gt;&nbsp;(a&nbsp;-&gt;&nbsp;Session&nbsp;prop)&nbsp;-&gt;&nbsp;Test appProperty&nbsp;name&nbsp;= &nbsp;&nbsp;testProperty&nbsp;name&nbsp;.&nbsp;<span style="color:blue;">fmap</span>&nbsp;(ioProperty&nbsp;.&nbsp;runSessionWithApp)</pre> </p> <p> This is the same function, just with a more restricted type. It states that for any <code>Arbitrary a, Show a</code>, a test is a function that takes <code>a</code> as input and returns a <code>Session prop</code>. This restricts tests to take a single input value, which means that you'll have to write all those properties in tupled, uncurried form. You could relax that requirement by introducing a <code>newtype</code> and a type class with an instance that recursively enables curried functions. That's what <a href="http://hackage.haskell.org/package/hspec-wai/docs/Test-Hspec-Wai-QuickCheck.html">Test.Hspec.Wai.QuickCheck</a> does. I decided not to add that extra level of indirection, and instead living with having to write all my properties in tupled form. </p> <p> The <code>Functor f</code> in the above, relaxed type, then, is in actual use the Reader functor. You'll see some examples next. </p> <h3 id="0ebc8724e39149e88e5e71763b03d499"> Properties <a href="#0ebc8724e39149e88e5e71763b03d499" title="permalink">#</a> </h3> <p> You can now define some properties. Here's a simple example: </p> <p> <pre>appProperty&nbsp;<span style="color:#a31515;">&quot;responds&nbsp;with&nbsp;404&nbsp;when&nbsp;no&nbsp;reservation&nbsp;exists&quot;</span>&nbsp;$&nbsp;\rid&nbsp;-&gt;&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;actual&nbsp;&lt;-&nbsp;get&nbsp;$&nbsp;<span style="color:#a31515;">&quot;/reservations/&quot;</span>&nbsp;&lt;&gt;&nbsp;toASCIIBytes&nbsp;rid &nbsp;&nbsp;assertStatus&nbsp;404&nbsp;actual</pre> </p> <p> This is an inlined property, similar to how <a href="/2018/05/07/inlined-hunit-test-lists">I inline HUnit tests in test lists</a>. </p> <p> First, notice that the property is written as a lambda expression, which means that it fits the mould of <code>a -&gt; Session prop</code>. The input value <code>rid</code> (<em>reservationID</em>) is a <a href="http://hackage.haskell.org/package/uuid/docs/Data-UUID.html">UUID</a> value (for which an <code>Arbitrary</code> instance exists via <a href="http://hackage.haskell.org/package/quickcheck-instances">quickcheck-instances</a>). </p> <p> While the test runs in the <code>Session</code> monad, the <code>do</code> notation makes <code>actual</code> an <code>SResponse</code> value that you can then assert with <code>assertStatus</code> (from <em>Network.Wai.Test</em>). </p> <p> This property reproduces an interaction like this: </p> <p> <pre>&amp; curl -v http://localhost:8080/reservations/db38ac75-9ccd-43cc-864a-ce13e90a71d8 * Trying ::1:8080... * TCP_NODELAY set * Trying 127.0.0.1:8080... * TCP_NODELAY set * Connected to localhost (127.0.0.1) port 8080 (#0) &gt; GET /reservations/db38ac75-9ccd-43cc-864a-ce13e90a71d8 HTTP/1.1 &gt; Host: localhost:8080 &gt; User-Agent: curl/7.65.1 &gt; Accept: */* &gt; * Mark bundle as not supporting multiuse &lt; HTTP/1.1 404 Not Found &lt; Transfer-Encoding: chunked &lt; Date: Tue, 02 Jul 2019 18:09:51 GMT &lt; Server: Warp/3.2.27 &lt; * Connection #0 to host localhost left intact</pre> </p> <p> The important result is that the status code is <code>404 Not Found</code>, which is also what the property asserts. </p> <p> If you need more than one input value to your property, you have to write the property in tupled form: </p> <p> <pre>appProperty&nbsp;<span style="color:#a31515;">&quot;fails&nbsp;when&nbsp;reservation&nbsp;is&nbsp;POSTed&nbsp;with&nbsp;invalid&nbsp;quantity&quot;</span>&nbsp;$&nbsp;\ &nbsp;&nbsp;(ValidReservation&nbsp;r,&nbsp;NonNegative&nbsp;q)&nbsp;-&gt;&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;invalid&nbsp;=&nbsp;r&nbsp;{&nbsp;reservationQuantity&nbsp;=&nbsp;<span style="color:blue;">negate</span>&nbsp;q&nbsp;} &nbsp;&nbsp;actual&nbsp;&lt;-&nbsp;postJSON&nbsp;<span style="color:#a31515;">&quot;/reservations&quot;</span>&nbsp;$&nbsp;encode&nbsp;invalid &nbsp;&nbsp;assertStatus&nbsp;400&nbsp;actual</pre> </p> <p> This property still takes a single input, but that input is a tuple where the first element is a <code>ValidReservation</code> and the second element a <code>NonNegative Int</code>. The <a href="/2019/09/02/naming-newtypes-for-quickcheck-arbitraries">ValidReservation newtype wrapper</a> ensures that <code>r</code> is a valid reservation record. This ensures that the property only exercises the path where the reservation quantity is zero or negative. It accomplishes this by negating <code>q</code> and replacing the <code>reservationQuantity</code> with that negative (or zero) number. </p> <p> It then encodes (with <a href="http://hackage.haskell.org/package/aeson">aeson</a>) the <code>invalid</code> reservation and posts it using the <code>postJSON</code> function. </p> <p> Finally it asserts that the HTTP status code is <code>400 Bad Request</code>. </p> <h3 id="ae5b3f7b07634799ad2af0d9a2ac668c"> Summary <a href="#ae5b3f7b07634799ad2af0d9a2ac668c" title="permalink">#</a> </h3> <p> After having tried using <em>Test.Hspec.Wai</em> for some time, I decided to refactor my tests to QuickCheck and HUnit. Once I figured out how <em>Network.Wai.Test</em> works, the remaining work wasn't too difficult. While there's little written documentation for the modules, the types (as usual) act as documentation. Using the types, and looking a little at the underlying code, I was able to figure out how to use the test API. </p> <p> You write tests against <em>wai</em> applications in the <code>Session</code> monad. You can then use <code>runSession</code> to turn the <code>Session</code> into an <code>IO</code> value. </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>. Picture archivist in F# https://blog.ploeh.dk/2019/09/16/picture-archivist-in-f 2019-09-16T05:59:00+00:00 Mark Seemann <div id="post"> <p> <em>A comprehensive code example showing how to implement a functional architecture in F#.</em> </p> <p> This article shows how to implement the <a href="/2019/08/26/functional-file-system">picture archivist architecture described in a previous article</a>. In short, the task is to move some image files to directories based on their date-taken metadata. The architectural idea is to load a directory structure from disk into an in-memory tree, manipulate that tree, and use the resulting tree to perform the desired actions: </p> <p> <img src="/content/binary/functional-file-system-interaction.png" alt="A functional program typically loads data, transforms it, and stores it again."> </p> <p> Much of the program will manipulate the tree data, which is immutable. </p> <p> The previous article showed how to implement the <a href="/2019/09/09/picture-archivist-in-haskell">picture archivist architecture in Haskell</a>. In this article, you'll see how to do it in <a href="https://fsharp.org">F#</a>. This is essentially a port of the <a href="https://www.haskell.org">Haskell</a> code. </p> <h3 id="949a876ffec843e09d4faa5ae1c1b4c5"> Tree <a href="#949a876ffec843e09d4faa5ae1c1b4c5" title="permalink">#</a> </h3> <p> You can start by defining a <a href="https://en.wikipedia.org/wiki/Rose_tree">rose tree</a>: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;Tree&lt;&#39;a,&nbsp;&#39;b&gt;&nbsp;=&nbsp;Node&nbsp;<span style="color:blue;">of</span>&nbsp;&#39;a&nbsp;*&nbsp;Tree&lt;&#39;a,&nbsp;&#39;b&gt;&nbsp;list&nbsp;|&nbsp;Leaf&nbsp;<span style="color:blue;">of</span>&nbsp;&#39;b</pre> </p> <p> If you wanted to, you could put all the <code>Tree</code> code in a reusable library, because none of it is coupled to a particular application, such as <a href="https://amzn.to/2V06Kji">moving pictures</a>. You could also write a comprehensive test suite for the following functions, but in this article, I'll skip that. </p> <p> Notice that this sort of tree explicitly distinguishes between internal and leaf nodes. This is necessary because you'll need to keep track of the directory names (the internal nodes), while at the same time you'll want to enrich the leaves with additional data - data that you can't meaningfully add to the internal nodes. You'll see this later in the article. </p> <p> While I typically tend to define F# types outside of modules (so that you don't have to, say, prefix the type name with the module name - <code>Tree.Tree</code> is so awkward), the rest of the tree code goes into a module, including two helper functions: </p> <p> <pre><span style="color:blue;">module</span>&nbsp;Tree&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;&#39;b&nbsp;-&gt;&nbsp;Tree&lt;&#39;a,&#39;b&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;leaf&nbsp;=&nbsp;Leaf &nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;&#39;a&nbsp;-&gt;&nbsp;Tree&lt;&#39;a,&#39;b&gt;&nbsp;list&nbsp;-&gt;&nbsp;Tree&lt;&#39;a,&#39;b&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;node&nbsp;x&nbsp;xs&nbsp;=&nbsp;Node&nbsp;(x,&nbsp;xs)</pre> </p> <p> The <code>leaf</code> function doesn't add much value, but the <code>node</code> function offers a curried alternative to the <code>Node</code> case constructor. That's occasionally useful. </p> <p> The rest of the code related to trees is also defined in the <code>Tree</code> module, but I'm going to present it formatted as free-standing functions. If you're confused about the layout of the code, the entire code base is <a href="https://github.com/ploeh/picture-archivist">available on GitHub</a>. </p> <p> The <a href="/2019/08/05/rose-tree-catamorphism">rose tree catamorphism</a> is this <code>cata</code> function: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;c&nbsp;list&nbsp;-&gt;&nbsp;&#39;c)&nbsp;-&gt;&nbsp;(&#39;b&nbsp;-&gt;&nbsp;&#39;c)&nbsp;-&gt;&nbsp;Tree&lt;&#39;a,&#39;b&gt;&nbsp;-&gt;&nbsp;&#39;c</span> <span style="color:blue;">let</span>&nbsp;<span style="color:blue;">rec</span>&nbsp;cata&nbsp;fd&nbsp;ff&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Leaf&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;ff&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;Node&nbsp;(x,&nbsp;xs)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;xs&nbsp;|&gt;&nbsp;List.map&nbsp;(cata&nbsp;fd&nbsp;ff)&nbsp;|&gt;&nbsp;fd&nbsp;x</pre> </p> <p> In the corresponding Haskell implementation of this architecture, I called this function <code>foldTree</code>, so why not retain that name? The short answer is that the naming conventions differ between Haskell and F#, and while I favour learning from Haskell, I still want my F# code to be as <a href="/2015/08/03/idiomatic-or-idiosyncratic">idiomatic</a> as possible. </p> <p> While I don't enforce that client code <em>must</em> use the <code>Tree</code> module name to access the functions within, I prefer to name the functions so that they make sense when used with qualified access. Having to write <code>Tree.foldTree</code> seems redundant. A more idiomatic name would be <code>fold</code>, so that you could write <code>Tree.fold</code>. The problem with that name, though, is that <code>fold</code> usually implies a list-biased <em>fold</em> (corresponding to <code>foldl</code> in Haskell), and I'll actually need that name for that particular purpose later. </p> <p> So, <code>cata</code> it is. </p> <p> In this article, tree functionality is (with one exception) directly or transitively implemented with <code>cata</code>. </p> <h3 id="3f30722983ad47bd83c88cec4ba80983"> Filtering trees <a href="#3f30722983ad47bd83c88cec4ba80983" title="permalink">#</a> </h3> <p> It'll be useful to be able to filter the contents of a tree. For example, the picture archivist program will only move image files with valid metadata. This means that it'll need to filter out all files that aren't image files, as well as image files without valid metadata. </p> <p> It turns out that it'll be useful to supply a function that throws away <code>None</code> values from a tree of <code>option</code> leaves. This is similar to <a href="https://msdn.microsoft.com/en-us/visualfsharpdocs/conceptual/list.choose%5B't%2C'u%5D-function-%5Bfsharp%5D">List.choose</a>, so I call it <code>Tree.choose</code>: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b&nbsp;option)&nbsp;-&gt;&nbsp;Tree&lt;&#39;c,&#39;a&gt;&nbsp;-&gt;&nbsp;Tree&lt;&#39;c,&#39;b&gt;&nbsp;option</span> <span style="color:blue;">let</span>&nbsp;choose&nbsp;f&nbsp;=&nbsp;cata&nbsp;(<span style="color:blue;">fun</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;List.choose&nbsp;id&nbsp;&gt;&gt;&nbsp;node&nbsp;x&nbsp;&gt;&gt;&nbsp;Some)&nbsp;(f&nbsp;&gt;&gt;&nbsp;Option.map&nbsp;Leaf)</pre> </p> <p> You may find the type of the function surprising. Why does it return a <code>Tree option</code>, instead of simply a <code>Tree</code>? </p> <p> While <code>List.choose</code> simply returns a list, it can do this because lists can be empty. This <code>Tree</code> type, on the other hand, can't be empty. If the purpose of <code>Tree.choose</code> is to throw away all <code>None</code> values, then how do you return a tree from <code>Leaf None</code>? </p> <p> You can't return a <code>Leaf</code> because you have no value to put in the leaf. Similarly, you can't return a <code>Node</code> because, again, you have no value to put in the node. </p> <p> In order to handle this edge case, then, you'll have to return <code>None</code>: </p> <p> <pre>&gt; let l : Tree&lt;string, int option&gt; = Leaf None;; val l : Tree&lt;string,int option&gt; = Leaf None &gt; Tree.choose id l;; val it : Tree&lt;string,int&gt; option = None</pre> </p> <p> If you have anything other than a <code>None</code> leaf, though, you'll get a proper tree, but wrapped in an <code>option</code>: </p> <p> <pre>&gt; Tree.node "Foo" [Leaf (Some 42); Leaf None; Leaf (Some 2112)] |&gt; Tree.choose id;; val it : Tree&lt;string,int&gt; option = Some (Node ("Foo",[Leaf 42; Leaf 2112]))</pre> </p> <p> While the resulting tree is wrapped in a <code>Some</code> case, the leaves contain unwrapped values. </p> <h3 id="32f46f2c16cf428abc39c3d79433caa6"> Bifunctor, functor, and folds <a href="#32f46f2c16cf428abc39c3d79433caa6" title="permalink">#</a> </h3> <p> Through its type class language feature, Haskell has formal definitions of <a href="/2018/03/22/functors">functors</a>, <a href="/2018/12/24/bifunctors">bifunctors</a>, and other types of <em>folds</em> (list-biased <a href="/2019/04/29/catamorphisms">catamorphisms</a>). F# doesn't have a similar degree of formalism, which means that while you can still implement the corresponding functionality, you'll have to rely on conventions to make the functions recognisable. </p> <p> It's straighforward to start with the bifunctor functionality: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;(&#39;c&nbsp;-&gt;&nbsp;&#39;d)&nbsp;-&gt;&nbsp;Tree&lt;&#39;a,&#39;c&gt;&nbsp;-&gt;&nbsp;Tree&lt;&#39;b,&#39;d&gt;</span> <span style="color:blue;">let</span>&nbsp;bimap&nbsp;f&nbsp;g&nbsp;=&nbsp;cata&nbsp;(f&nbsp;&gt;&gt;&nbsp;node)&nbsp;(g&nbsp;&gt;&gt;&nbsp;leaf)</pre> </p> <p> This is, apart from the syntax differences, the same implementation as in Haskell. Based on <code>bimap</code>, you can also trivially implement <code>mapNode</code> and <code>mapLeaf</code> functions if you'd like, but you're not going to need those for the code in this article. You do need, however, a function that we could consider an alias of a hypothetical <code>mapLeaf</code> function: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;b&nbsp;-&gt;&nbsp;&#39;c)&nbsp;-&gt;&nbsp;Tree&lt;&#39;a,&#39;b&gt;&nbsp;-&gt;&nbsp;Tree&lt;&#39;a,&#39;c&gt;</span> <span style="color:blue;">let</span>&nbsp;map&nbsp;f&nbsp;=&nbsp;bimap&nbsp;id&nbsp;f</pre> </p> <p> This makes <code>Tree</code> a functor. </p> <p> It'll also be useful to reduce a tree to a potentially more compact value, so you can add some specialised folds: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;c&nbsp;-&gt;&nbsp;&#39;a&nbsp;-&gt;&nbsp;&#39;c)&nbsp;-&gt;&nbsp;(&#39;c&nbsp;-&gt;&nbsp;&#39;b&nbsp;-&gt;&nbsp;&#39;c)&nbsp;-&gt;&nbsp;&#39;c&nbsp;-&gt;&nbsp;Tree&lt;&#39;a,&#39;b&gt;&nbsp;-&gt;&nbsp;&#39;c</span> <span style="color:blue;">let</span>&nbsp;bifold&nbsp;f&nbsp;g&nbsp;z&nbsp;t&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;flip&nbsp;f&nbsp;x&nbsp;y&nbsp;=&nbsp;f&nbsp;y&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;cata&nbsp;(<span style="color:blue;">fun</span>&nbsp;x&nbsp;xs&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;flip&nbsp;f&nbsp;x&nbsp;&gt;&gt;&nbsp;List.fold&nbsp;(&gt;&gt;)&nbsp;id&nbsp;xs)&nbsp;(flip&nbsp;g)&nbsp;t&nbsp;z <span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;c&nbsp;-&gt;&nbsp;&#39;c)&nbsp;-&gt;&nbsp;(&#39;b&nbsp;-&gt;&nbsp;&#39;c&nbsp;-&gt;&nbsp;&#39;c)&nbsp;-&gt;&nbsp;Tree&lt;&#39;a,&#39;b&gt;&nbsp;-&gt;&nbsp;&#39;c&nbsp;-&gt;&nbsp;&#39;c</span> <span style="color:blue;">let</span>&nbsp;bifoldBack&nbsp;f&nbsp;g&nbsp;t&nbsp;z&nbsp;=&nbsp;cata&nbsp;(<span style="color:blue;">fun</span>&nbsp;x&nbsp;xs&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;List.foldBack&nbsp;(&lt;&lt;)&nbsp;xs&nbsp;id&nbsp;&gt;&gt;&nbsp;f&nbsp;x)&nbsp;g&nbsp;t&nbsp;z</pre> </p> <p> In an attempt to emulate the F# naming conventions, I named the functions as I did. There are similar functions in the <code>List</code> and <code>Option</code> modules, for instance. If you're comparing the F# code with the Haskell code in the previous article, <code>Tree.bifold</code> corresponds to <code>bifoldl</code>, and <code>Tree.bifoldBack</code> corresponds to <code>bifoldr</code>. </p> <p> These enable you to implement folds over leaves only: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;c&nbsp;-&gt;&nbsp;&#39;b&nbsp;-&gt;&nbsp;&#39;c)&nbsp;-&gt;&nbsp;&#39;c&nbsp;-&gt;&nbsp;Tree&lt;&#39;a,&#39;b&gt;&nbsp;-&gt;&nbsp;&#39;c</span> <span style="color:blue;">let</span>&nbsp;fold&nbsp;f&nbsp;=&nbsp;bifold&nbsp;(<span style="color:blue;">fun</span>&nbsp;x&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x)&nbsp;f <span style="color:green;">//&nbsp;(&#39;b&nbsp;-&gt;&nbsp;&#39;c&nbsp;-&gt;&nbsp;&#39;c)&nbsp;-&gt;&nbsp;Tree&lt;&#39;a,&#39;b&gt;&nbsp;-&gt;&nbsp;&#39;c&nbsp;-&gt;&nbsp;&#39;c</span> <span style="color:blue;">let</span>&nbsp;foldBack&nbsp;f&nbsp;=&nbsp;bifoldBack&nbsp;(<span style="color:blue;">fun</span>&nbsp;_&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x)&nbsp;f</pre> </p> <p> These, again, enable you to implement another function that'll turn out to be useful in this article: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;b&nbsp;-&gt;&nbsp;unit)&nbsp;-&gt;&nbsp;Tree&lt;&#39;a,&#39;b&gt;&nbsp;-&gt;&nbsp;unit</span> <span style="color:blue;">let</span>&nbsp;iter&nbsp;f&nbsp;=&nbsp;fold&nbsp;(<span style="color:blue;">fun</span>&nbsp;()&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;f&nbsp;x)&nbsp;()</pre> </p> <p> The picture archivist program isn't going to explicitly need all of these, but transitively, it will. </p> <h3 id="8a9a50c69a2d461cac5bb87fa4cf3cd9"> Moving pictures <a href="#8a9a50c69a2d461cac5bb87fa4cf3cd9" title="permalink">#</a> </h3> <p> So far, all the code shown here could be in a general-purpose reusable library, since it contains no functionality specifically related to image files. The rest of the code in this article, however, will be specific to the program. I'll put the domain model code in another module that I call <code>Archive</code>. Later in the article, we'll look at how to load a tree from the file system, but for now, we'll just pretend that we have such a tree. </p> <p> The major logic of the program is to create a destination tree based on a source tree. The leaves of the tree will have to carry some extra information apart from a file path, so you can introduce a specific type to capture that information: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;PhotoFile&nbsp;=&nbsp;{&nbsp;File&nbsp;:&nbsp;FileInfo;&nbsp;TakenOn&nbsp;:&nbsp;DateTime&nbsp;}</pre> </p> <p> A <code>PhotoFile</code> not only contains the file path for an image file, but also the date the photo was taken. This date can be extracted from the file's metadata, but that's an impure operation, so we'll delegate that work to the start of the program. We'll return to that later. </p> <p> Given a source tree of <code>PhotoFile</code> leaves, though, the program must produce a destination tree of files: </p> <p> <pre><span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;Tree&lt;&#39;a,PhotoFile&gt;&nbsp;-&gt;&nbsp;Tree&lt;string,FileInfo&gt;</span> <span style="color:blue;">let</span>&nbsp;moveTo&nbsp;destination&nbsp;t&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;dirNameOf&nbsp;(dt&nbsp;:&nbsp;DateTime)&nbsp;=&nbsp;sprintf&nbsp;<span style="color:#a31515;">&quot;%d-%02d&quot;</span>&nbsp;dt.Year&nbsp;dt.Month &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;groupByDir&nbsp;pf&nbsp;m&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;key&nbsp;=&nbsp;dirNameOf&nbsp;pf.TakenOn &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;dir&nbsp;=&nbsp;Map.tryFind&nbsp;key&nbsp;m&nbsp;|&gt;&nbsp;Option.defaultValue&nbsp;[] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Map.add&nbsp;key&nbsp;(pf.File&nbsp;::&nbsp;dir)&nbsp;m &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;addDir&nbsp;name&nbsp;files&nbsp;dirs&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Tree.node&nbsp;name&nbsp;(List.map&nbsp;Leaf&nbsp;files)&nbsp;::&nbsp;dirs &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;m&nbsp;=&nbsp;Tree.foldBack&nbsp;groupByDir&nbsp;t&nbsp;Map.empty &nbsp;&nbsp;&nbsp;&nbsp;Map.foldBack&nbsp;addDir&nbsp;m&nbsp;[]&nbsp;|&gt;&nbsp;Tree.node&nbsp;destination</pre> </p> <p> This <code>moveTo</code> function looks, perhaps, overwhelming, but it's composed of three conceptual steps: <ol> <li>Create a map of destination folders (<code>m</code>).</li> <li>Create a list of branches from the map (<code>Map.foldBack addDir m []</code>).</li> <li>Create a tree from the list (<code>Tree.node destination</code>).</li> </ol> The <code>moveTo</code> function starts by folding the input data into a map <code>m</code>. The map is keyed by the directory name, which is formatted by the <code>dirNameOf</code> function. This function takes a <code>DateTime</code> as input and formats it to a <code>YYYY-MM</code> format. For example, December 20, 2018 becomes <code>"2018-12"</code>. </p> <p> The entire mapping step groups the <code>PhotoFile</code> values into a map of the type <code>Map&lt;string,FileInfo list&gt;</code>. All the image files taken in April 2014 are added to the list with the <code>"2014-04"</code> key, all the image files taken in July 2011 are added to the list with the <code>"2011-07"</code> key, and so on. </p> <p> In the next step, the <code>moveTo</code> function converts the map to a list of trees. This will be the branches (or sub-directories) of the <code>destination</code> directory. Because of the desired structure of the destination tree, this is a list of shallow branches. Each node contains only leaves. </p> <p> <img src="/content/binary/shallow-photo-destination-directories.png" alt="Shallow photo destination directories."> </p> <p> The only remaining step is to add that list of branches to a <code>destination</code> node. This is done by piping (<code>|&gt;</code>) the list of sub-directories into <code>Tree.node destination</code>. </p> <p> Since this is a <a href="https://en.wikipedia.org/wiki/Pure_function">pure function</a>, it's <a href="/2015/05/07/functional-design-is-intrinsically-testable">easy to unit test</a>. Just create some test cases and call the function. First, the test cases. </p> <p> In this code base, I'm using <a href="https://xunit.github.io">xUnit.net</a> 2.4.1, so I'll first create a set of test cases as a test-specific class: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;MoveToDestinationTestData&nbsp;()&nbsp;<span style="color:blue;">as</span>&nbsp;this&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;TheoryData&lt;Tree&lt;string,&nbsp;PhotoFile&gt;,&nbsp;string,&nbsp;Tree&lt;string,&nbsp;string&gt;&gt;&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;photoLeaf&nbsp;name&nbsp;(y,&nbsp;mth,&nbsp;d,&nbsp;h,&nbsp;m,&nbsp;s)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp