<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Floyd May on Medium]]></title>
        <description><![CDATA[Stories by Floyd May on Medium]]></description>
        <link>https://medium.com/@floyd.may?source=rss-aa761b7e3c3------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*sYpJWSvIi-swDAZLNWgBVw.jpeg</url>
            <title>Stories by Floyd May on Medium</title>
            <link>https://medium.com/@floyd.may?source=rss-aa761b7e3c3------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 13:27:23 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@floyd.may/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[On Checking in Commented-out Code]]></title>
            <link>https://medium.com/@floyd.may/on-checking-in-commented-out-code-e32cd9c26ea3?source=rss-aa761b7e3c3------2</link>
            <guid isPermaLink="false">https://medium.com/p/e32cd9c26ea3</guid>
            <category><![CDATA[code-review]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[coding]]></category>
            <dc:creator><![CDATA[Floyd May]]></dc:creator>
            <pubDate>Thu, 25 Sep 2025 15:18:08 GMT</pubDate>
            <atom:updated>2025-09-25T15:18:08.660Z</atom:updated>
            <content:encoded><![CDATA[<p>So there is an initiation that every developer who works with me eventually gets, and that relates to commented-out code:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/692/0*Oja6OBSDa2yBLR3o" /></figure><p>I will always challenge commented-out code being kept “in case” of some future possibility. Tiptoeing around commented-out code to protect ourselves from an eventual future where we’ll need it is the opposite of <a href="https://martinfowler.com/bliki/Yagni.html">YAGNI</a>. It’s <em>Hoarders, the Developer Edition</em>. The value of beanie babies is never going to go up enough to warrant keeping them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/225/0*rF5HDNu6fu_NyKnE" /></figure><p><em>Just delete the code.</em> Our git repository solves the problem of “if we need it later.” Always, always, always, delete code if you want to remove it. Don’t comment it out. Think of the kittens.</p><p>P.S. in future code reviews if you see me comment “kitten murder”, now you know why.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e32cd9c26ea3" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building the Skills that Matter]]></title>
            <link>https://medium.com/@floyd.may/building-the-skills-that-matter-c0df3b5353ef?source=rss-aa761b7e3c3------2</link>
            <guid isPermaLink="false">https://medium.com/p/c0df3b5353ef</guid>
            <category><![CDATA[coding]]></category>
            <category><![CDATA[getting-hired]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[Floyd May]]></dc:creator>
            <pubDate>Mon, 26 Sep 2022 19:18:58 GMT</pubDate>
            <atom:updated>2022-09-26T19:18:58.192Z</atom:updated>
            <content:encoded><![CDATA[<p>Last week I published a <a href="https://medium.com/@floyd.may/the-skills-that-matter-and-how-to-build-them-495ecc4d42ea">list of four skills</a> that I said matter for software developers:</p><ul><li>Coding</li><li>Communication</li><li>Responding to Feedback</li><li>Managing Complexity</li></ul><p>These are the skills that determine a hire/no hire decision for me. Naturally, I got feedback in my local community asking, “How do I build those skills?” Here are my recommendations.</p><h4>Code Katas</h4><p>I cannot overstate how helpful code katas are in building and reinforcing the ability to <em>write code</em>. Practicing code katas reinforces a number of skills and techniques that are essential to the practice of software development. First, it helps to create a solid understanding of the programming language’s features: syntax, built-in functions, build and test tooling, and so on. I’ve often used code katas to learn new languages or to refresh my understanding of languages that I haven’t used in a while. Second, code katas strengthen the connection between brain and keyboard. I often say that katas help one learn to code at the speed of thought. The repetition of re-solving the problem again and again helps to improve typing speed and precision, encourages using keyboard shortcuts and advanced IDE features, and discourages reliance on using the mouse.</p><p>If you need some help getting started, I’d recommend the bowling kata. Here’s a <a href="https://youtu.be/OPGTPQ4kURU">great example video</a> of this kata in action. What I’ll often do for new programmers is challenge them to get all the way through the implementation of scoring an entire game of bowling, including the special cases for the final frame, in under thirty minutes. Practice, practice, practice! If you can accomplish this, it almost certainly means you’re typing at a brisk pace. You’re probably using IDE shortcuts. You’re not googling for syntax or how built-in library functions work. And — if you’re not cheating (more below) — you’re beginning to smoothly translate thought into code.</p><p>It’s possible to cheat while working through a coding kata. In the case of the bowling kata, the goal is to strengthen TDD practice. The bowling kata, in particular, is all about that third phase of TDD: refactoring. If you address the bowling kata by regurgitating the final solution from memory, you’re missing the point. That’s cheating. The point is to build the skill of refactoring code as you add new features. I may be able to produce a correct scoring algorithm for bowling without refactoring and without any tests, but <em>I wouldn’t be strengthening my technique by doing so</em>. Another cheat that often shows up in the bowling kata is working ahead: building more complexity than what’s driven by failing tests. If a simpler solution would make your tests pass, you must use the simpler solution. Again, the goal of this kata is refactoring: restructuring code while preserving the behavior. If you work ahead, you don’t build the skill of evolving simple solutions into more complex ones.</p><p>You might be wondering, “Do katas really make someone worth hiring?” It’s a fair question. So, let’s say you can do the bowling kata, without cheating, in thirty minutes. Here’s why that’s valuable to a potential employer. First, it proves that you can actually write code. Many, many programmers and aspiring programmers can <em>barely write code</em>. Completing the bowling kata in half an hour sets you ahead of the majority. Second, it demonstrates that you can write clean code and tests. Third, watching you work through the problem makes it very easy for potential employers (like me) to see your software design skills in action. In short, practicing a code kata will make you tremendously more hirable.</p><h4>Communication Skills</h4><p>Two of my criteria for hiring are non-technical. I need to see that you can think out loud, and I need to see that you can productively accept critique. I won’t hire someone unless they can work well with others. Prima donnas are a liability. Loners are huge risks. Communication skills and teamwork are non-negotiables. If you can’t do this, <em>I won’t hire you</em>.</p><p>I’ll make two recommendations for building these skills. The first centers around the coding kata. This time, instead of it being a solo activity that you repeatedly practice to build skill, it will be a performance art. Perform a kata for an audience; preferably, non-programmers. One or two people is fine. Narrate your steps, explain what you’re doing, and gather their impressions when you’re done. This will help you understand a few key things. First, are you writing clear, readable code? If your audience says things like, “I don’t understand programming, but what you wrote made sense to me as you did it,” this is a good sign. If not, maybe focus more on refactoring for readability. Next, you will learn if you explained things well. If your audience was lost or bored, use this to tune up your explanation skills. And finally, this will help you learn to accept critique. If you find yourself frustrated, defensive, or making excuses when your non-programmer audience suggests unreasonable changes, you may need to reflect upon why you respond poorly.</p><p>My second recommendation would be to build something, anything (preferably small), then seek out an experienced programmer to give you feedback on how you did. Is it in an idiomatic style for the programming language it’s written in? Is it clear, readable, maintainable? Is it overly complex, or straightforward? Is there a better way to do it? And then, reflect on that feedback, and <em>act on it</em>. Make some of those suggested changes, even if you disagree, and take those changes back to the reviewer. Invite feedback, and act on it. Learn to accept critique.</p><h4>ABC: Always Be Coding</h4><p>My final piece of advice for building programming skill is <em>write code</em>. Do katas. Make PRs to open source projects. Build little programs. Rebuild programs that you’ve built in the past, but in a different programming language, or a different style. Practice, practice, practice. See if you can find someone to pair up with on building some program, or adding some feature to an open source project. There’s no blog, book, or educational video that can replace the skills that you build when you, yourself, write code. So go write code.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c0df3b5353ef" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Skills That Matter, and How to Build Them]]></title>
            <link>https://medium.com/@floyd.may/the-skills-that-matter-and-how-to-build-them-495ecc4d42ea?source=rss-aa761b7e3c3------2</link>
            <guid isPermaLink="false">https://medium.com/p/495ecc4d42ea</guid>
            <category><![CDATA[hiring]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Floyd May]]></dc:creator>
            <pubDate>Thu, 22 Sep 2022 13:40:00 GMT</pubDate>
            <atom:updated>2022-09-25T21:46:00.983Z</atom:updated>
            <content:encoded><![CDATA[<h3>The Software Dev Skills That Matter</h3><p>I’ve been involved in hiring software developers for over a decade. I’ve seen which skills matter in building a successful career, and which ones don’t. And I’ve seen how the software industry over-focuses on too many tactical, fleeting skills, and fails to emphasize the skills that actually matter. What follows is an explanation of the skillset — the only skillset — that goes into my hiring recommendations. Whether I’m hiring a junior position or a senior position, these are the skills that matter.</p><h3>Coding</h3><p>A software developer needs to be able to write code effectively. It’s almost ridiculous, shameful, that I should have to call this out, but it clearly isn’t something one can assume. After over two decades in software development, I’ve found that there are far too many developers drawing paychecks for writing software that <em>can barely write code, if at all</em>. I say often that if I were hiring jugglers for a circus, I wouldn’t hire a single one without actually seeing them juggle. Therefore, I won’t hire a programmer that I haven’t seen write code.</p><p>What do I look for? I look for proficiency. Is this person comfortable with the syntax, or do they stumble along? Do they pay attention to the warnings and errors that the compiler, the IDE, and other tooling provide? Can they turn the idea they have in their head into actual working code in a reasonable amount of time? Are they good at using the keyboard? The editor or IDE? Do they format their code according to whatever the idiom is for the programming language at hand? Can this supposed juggler actually <em>juggle</em>?</p><h3>Communication</h3><p>The next thing I look for is if a developer can “think out loud” effectively. I need to see if this person can clearly communicate their thought process, because communication — especially in such a technical context — is the foundation of collaboration and productivity. Can I understand this person’s intent? If I can’t deduce what they’re doing from how they’re writing code, can they fill in the gaps verbally? Does speaking with them make things clearer… or more confusing? Do they answer questions clearly and directly? Do they use technical terminology correctly? When they’re confused or operating at the limits of their skills, can they be vulnerable and say so?</p><h3>Responding to Feedback</h3><p>I also look for a developer’s ability to respond to feedback. That is, can they productively change course when someone insists on going a different direction? Programming is often a team sport, and I need to see that someone can be a team player. In interviews, I will intentionally insist on asking developers to restructure their code in different ways to see how they respond. Too many developers, unfortunately, are married to their code, and struggle to incorporate another person’s perspective into it. When a programmer can abandon ego for the sake of productive collaboration, that’s a skill worth hiring for.</p><h3>Managing Complexity</h3><p>Complexity is a programmer’s eternal enemy, and I need to see that a programmer knows their enemy and how to battle it. Do they write good tests that clearly illuminate the intended behavior and keep bugs at bay? Do they use good names for variables, classes, functions, and so on? Do they break apart large functions, classes, and files into smaller ones when they get too big? Do they have a healthy distrust for repetitive code? Do they avoid deeply-nested control structures? I won’t hire a programmer that carelessly slings code.</p><p>If I directly observe that a programmer has the above qualities, there’s a good chance I’ll hire them (or recommend hiring them if I’m not the hiring manager). What might be conspicuously absent from my criteria are things like:</p><ul><li>Do they know React/Vue/Angular/Flerble/what-our-stuff-is-written-in?</li><li>Can they do a linked list insert?</li><li>Can they estimate how many ping pong balls would fit in a school bus?</li><li>Do they know SQL?</li><li>Do they know CloudFormation/Terraform/ARM Templates (or whatever our infra automation is written in)?</li><li>Have they worked with <a href="https://medium.com/@floyd.may/floyds-nonsensical-stance-on-dependency-injection-479b06609e99">ũberCloud HyperMessage BusFabricServer</a>?</li></ul><p>What I’ve discovered, after over twenty years, is that aptitude and core skills matter a lot more than having “the right answers”. I’ve seen what happens when hiring focuses on tech stack familiarity instead of skill and aptitude. Hiring for someone who already knows the stack with the intent that they can “hit the ground running” may sound good, but beware. Without those core skills and aptitudes, stack familiarity just speeds up the rate at which bad code and bugs pile up. In contrast, people that pass my criteria have invariably proven themselves to be good hires. I hire for that, and let them learn the details on the job. So far, it’s been working pretty well.</p><p>(pardon the shameless self-promotion, but if you need help with screening software development candidates, upskilling your team(s), or leading a software development effort, <a href="https://canyon-trail.com/">reach out</a>.)</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=495ecc4d42ea" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Async Superpowers — Some Guidance]]></title>
            <link>https://medium.com/@floyd.may/async-superpowers-some-guidance-a72340733a0e?source=rss-aa761b7e3c3------2</link>
            <guid isPermaLink="false">https://medium.com/p/a72340733a0e</guid>
            <category><![CDATA[unit-testing]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[ui]]></category>
            <category><![CDATA[computer-science]]></category>
            <dc:creator><![CDATA[Floyd May]]></dc:creator>
            <pubDate>Wed, 29 Dec 2021 20:49:53 GMT</pubDate>
            <atom:updated>2021-12-29T20:49:53.056Z</atom:updated>
            <content:encoded><![CDATA[<h3>Async Superpowers — Some Guidance</h3><p>This is the final article in a series, <em>Async Superpowers: State Machines</em>, geared for helping you understand how to easily build and test¹ UIs that have asynchronous things going on. The first article in the series is <a href="https://medium.com/@floyd.may/asyc-superpowers-state-machines-58abdf24aaa">here</a>.</p><p>Here in this last article, I’d like to spend some time giving you some general guidance as you learn how to use state machines to tame UIs. All of what you’re about to read comes from real-world experience. In other words, this is how I’ve messed it up in the past.</p><h4>Ignoring Irrelevant Actions</h4><p>One of the beauties of using a state machine to manage a UI is that the machine ignores irrelevant actions. For instance, let’s consider a classic problem. An over-eager user² double-clicks a button that, say, makes a purchase, and causes the purchase to be duplicated³. In this kind of situation, any subsequent clicks after the first one should be ignored. When we use a state machine to manage these interactions, the button click should dispatch an action that causes a state transition:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/790/1*cBbNk9BDipdsxKV5iMRvmg.png" /><figcaption>A part of a potential state machine for our purchase scenario.</figcaption></figure><p>Given the state machine above, the button click would dispatch the Confirm purchase action, and our state machine would transition to the Purchase pending state. Even if rapid-fire clicking manages to dispatch more than one Confirm purchase action, our state machine ignores all but the first of those actions.</p><h4>Initiate Asynchronous Operations from States</h4><p>In our purchase example above, a key element of preventing duplicate purchase attempts is that we initiate the HTTP call <strong>only </strong>when we arrive at the Purchase pending state. It is the <em>state</em> that indicates when to invoke the HTTP call and <strong>not the </strong><strong>Confirm purchase action. </strong>Always initiate asynchronous operations based on the <em>state; </em>never based on an action. This keeps the state machine in control of which actions are (and are not) relevant. If you review the “async reactor” we built in the previous article, it initiates async operations based on the state, and never the action.</p><h4>Reference Equality on Ignored Actions</h4><p>A key element that prevents our async reactor from duplicating asynchronous operations is the useEffect hook in React. It only invokes the callback when the given state changes:</p><pre>useEffect(() =&gt; {<br>  reactToState(state, dispatch);<br>}, [state]);</pre><p>Regardless of how many times this component is re-rendered, the call to reactToState(...) will only be invoked if state changes vis a vis <em>reference equality</em>; that is, if the new value of state is not the exact same object it was previously. If, say, when processing a duplicate Confirm purchase action, our reducer function returned { ...state } (that is, generating a new, equivalent object with the same data) rather than state, this useEffect(...) callback would be invoked again, possibly attempting a duplicate purchase.</p><p>Whether or not you’re using React, your async reactor should only initiate communications when the state <strong>changes</strong>. The simplest solution to this is to ensure that your reducer returns <strong>the same state</strong> when it ignores an action and never returns a clone or copy of the state. This ensures that a new state object is produced <em>only</em> when a state transition has occurred. If you aren’t careful about this, some potential problems could include:</p><ul><li>Repeatedly sending duplicate HTTP requests</li><li>Infinite loops</li><li>Stack overflows</li></ul><p>Always make sure you return the <em>exact same state</em> when an action is ignored.</p><h4>There Is No Such Thing As In-between States</h4><p>You may find yourself tempted to have things happen “between” states; that is, your UI might have an animation or something like it that’s timing-related, but quick, and you’d rather not model that “in between” transitionary part as yet another state in your state machine. Resist that temptation.</p><h4>Watch Out for Complexity</h4><p>Be aware of how complex your state machines are. A machine with four to six states is pretty comfortable to work with. Nine or ten states will often start becoming unwieldy, and a dozen states is almost certain to be too complex.</p><p>When you discover that a state machine has become too complex, revisit your UI to see if you can decompose it into separate components that use simpler state machines.</p><h3>Conclusion: Guiding Principles</h3><p>Now that you’re ready to try out your new async superpowers and tame some UIs, let me give you a quick list of what we’ve covered:</p><ul><li><strong>Model your UI as a set of states<br></strong>This lets you can easily build and test the visual representation of each state in isolation, especially those tricky “loading” states. Be sure to test that the UI dispatches the correct actions given specific user input.</li><li><strong>Design a state machine<br></strong>Put the state machine in control of which actions allow transitions from one state to another. Make sure that your machine ignores invalid or irrelevant actions.</li><li><strong>React to state changes</strong><br>Initiate asynchronous communications in a “reactor” that reacts to changes to the <em>state </em>(and not to dispatched actions).</li><li><strong>Write good tests</strong><br>Each component should be thoroughly testable in isolation, and one or two higher-level integration tests can help ensure that everything is working together as intended</li></ul><h4>Footnotes</h4><ol><li>Yes, <strong>those</strong> tests. You know. Automated ones.</li><li>Or a clever QA engineer.</li><li>A well-designed backend wouldn’t allow this, and would likely produce errors on subsequent attempts to confirm a purchase.</li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a72340733a0e" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Async Superpowers, Part 3]]></title>
            <link>https://medium.com/@floyd.may/async-superpowers-part-3-ac740bd84177?source=rss-aa761b7e3c3------2</link>
            <guid isPermaLink="false">https://medium.com/p/ac740bd84177</guid>
            <category><![CDATA[unit-testing]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[computer-science]]></category>
            <category><![CDATA[ui]]></category>
            <dc:creator><![CDATA[Floyd May]]></dc:creator>
            <pubDate>Wed, 29 Dec 2021 20:33:09 GMT</pubDate>
            <atom:updated>2021-12-29T21:03:48.280Z</atom:updated>
            <content:encoded><![CDATA[<p>This is the third in an four-part series that will help you easily write and test UIs that do asynchronous stuff.</p><h4>Recap</h4><p>In the <a href="https://medium.com/@floyd.may/asyc-superpowers-state-machines-58abdf24aaa">previous</a> <a href="https://medium.com/@floyd.may/async-superpowers-part-2-1c55b04128fe">two</a> articles, we learned about how to model real-world computing problems with a <em>state machine</em>. We played with parsing strings, controlling a rollercoaster, and modeling a search UI. We also showed how we use a <em>state</em> and its associated data to prove (via automated tests) that the UI renders properly when it’s in a given state. We also proved that the UI dispatches <em>actions</em> in response to user input.</p><figure><img alt="" src="https://cdn-images-1.medium.com/proxy/1*xtJMZNlqHBpjApg1sU4mKg.png" /><figcaption>The state machine that drives our search UI.</figcaption></figure><h4>Connecting It All Together</h4><p>We have two remaining problems to solve. One, we need to “drive” our state machine so that actions cause the UI’s state to change; and two, we need to initiate those asynchronous communications at the right times and dispatch actions when they complete.</p><p><em>(Quick note: I’m using React for my code samples here, but don’t let that deter you if you’re using some other tech! This technique is applicable in any programming language and/or UI framework.)</em></p><p>For the first problem, we’ll use <a href="https://reactjs.org/docs/hooks-reference.html#usereducer">React’s </a><a href="https://reactjs.org/docs/hooks-reference.html#usereducer">useReducer hook</a>. This is, unsurprisingly, built <em>exactly for</em> usages like ours:</p><pre>const ThingSearchUI = () =&gt; {<br>  const [state, dispatch] = useReducer(reducer, { tag: &quot;Loading&quot; });</pre><pre>  return &lt;ThingSearch state={state} dispatch={dispatch} /&gt;;<br>};</pre><p>Let’s take a closer look. The useReducer function accepts a reducer function (the reducer we built in the previous article), and an <em>initial state</em>. In our case, the initial state for our state machine is Loading. The return values are the current state and a dispatch function. Notice how we’re passing this state and dispatch directly to ThingSearch, which we also learned how to test in the previous article. Now, our UI renders itself properly in each state <strong>and</strong> actions generated from user input are now “connected” to our reducer function, causing the state machine to transition.</p><p>If you’re using some other framework, you could replicate useReducer using something like this:</p><pre>// assuming `this.state` and `this.dispatch` are available<br>//  for use in your child components (or similar)<br>class ThingSearch extends Component {<br>  onInit() {<br>    this.state = { tag: &quot;Loading&quot; };<br>  }</pre><pre>  dispatch(action: Action) {<br>    this.state = reducer(this.state, action);<br>  }<br>}</pre><p>Next, we need to initiate those asynchronous communications at the right times. For the three “asynchronous result” transitions in our state machine, they begin at the Loading, Reloading, and Loading More states. So, when our machine arrives at each state, we should initiate those asynchronous calls (like, say, using the fetch API to get some data over HTTP). So, we could write a function that, given a state and a dispatch function, makes the correct fetch call and dispatches the correct action:</p><pre>async function reactToState(state, dispatch) {<br>  if(state.tag === &quot;Loading&quot; || state.tag === &quot;Reloading&quot;) {<br>    const response = fetch({<br>      method: &quot;POST&quot;,<br>      path: &quot;/api/thingsearch&quot;,<br>      content: { state.searchText, /* ... */ }<br>    });<br>    const data = await response.json();</pre><pre>    dispatch({<br>      tag: &quot;Data Loaded&quot;,<br>      things: data.things,<br>      /* ... */<br>    });<br>  }<br>  /* and so on */<br>}</pre><p>Then, we can fashion a React component that uses this function when the state changes:</p><pre>const ThingSearchReactor = ({ state, dispatch }) =&gt; {<br>  useEffect(() =&gt; {<br>    reactToState(state, dispatch);<br>  }, [state]);</pre><pre>  return &lt;React.Fragment /&gt;<br>}</pre><p>I call this kind of component that only listens for state changes and initiates asynchronous operations an “async reactor”. Tests for this component would likely check for initiating the right HTTP communications given some state, and dispatching the correct action when the HTTP call completes. Then, finally, we can compose the entire thing together like this:</p><pre>const ThingSearchUI = () =&gt; {<br>  const [state, dispatch] = useReducer(reducer, { tag: &quot;Loading&quot; });</pre><pre>return (&lt;&gt;<br>  &lt;ThingSearch state={state} dispatch={dispatch} /&gt;<br>  &lt;ThingSearchReactor state={state} dispatch={dispatch} /&gt;<br>  &lt;/&gt;);<br>};</pre><h3>Zooming Out</h3><p>At this point, let’s take a step back and revisit what problem we were solving and see how all of these disjointed code snippets fit together. We have a “Thing Search” UI that has a search box, some dropdowns, and a list of “things”:</p><figure><img alt="" src="https://cdn-images-1.medium.com/proxy/1*0m-xyxJDidWLA_PZK2tCCQ.png" /></figure><p>This UI has a number of states where we’re waiting for asynchronous operations to complete. Our solution for this has three major components:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-1xw94moefIzx9UqdoFRlw.png" /></figure><ul><li><strong>The state machine<br></strong>This is implemented as a <em>reducer function</em> that accepts a current State and an Action and returns a new State. We modeled every behavior of our UI, including user interactions and asynchronous results, into this state machine.</li><li><strong>The display component</strong><br>This is the portion that displays UI based on a given State and dispatches Actions when the user interacts with the UI.</li><li><strong>The async reactor<br></strong>This component listens for state changes and initiates the asynchronous communications for our various “loading” states.</li></ul><p>Each of these components can be thoroughly and easily unit tested in isolation, and composing them together is quite simple. A larger-scale “integration” test or two¹ could ensure that we’ve composed these pieces correctly.</p><p>A working example app based on create-react-app is posted <a href="https://github.com/canyon-trail/state-machine-demo">here</a> (thanks GitHub!). In the <a href="https://medium.com/@floyd.may/async-superpowers-some-guidance-a72340733a0e">final article</a> in this series, we’ll discuss some design guidance for modeling your own UIs using state machines and explore some common pitfalls. Stick around!</p><h4>Footnotes</h4><ol><li>No, we’re not going to have an argument about what is and isn’t an integration test</li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ac740bd84177" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Async Superpowers, Part 2]]></title>
            <link>https://medium.com/@floyd.may/async-superpowers-part-2-1c55b04128fe?source=rss-aa761b7e3c3------2</link>
            <guid isPermaLink="false">https://medium.com/p/1c55b04128fe</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[computer-science]]></category>
            <category><![CDATA[unit-testing]]></category>
            <category><![CDATA[ui]]></category>
            <dc:creator><![CDATA[Floyd May]]></dc:creator>
            <pubDate>Wed, 29 Dec 2021 20:30:34 GMT</pubDate>
            <atom:updated>2021-12-29T20:33:34.780Z</atom:updated>
            <content:encoded><![CDATA[<p>This is the second in a four-part series that will help you easily write and test UIs that do asynchronous stuff.</p><p>(<em>Heads up: I’ll be doing pseudocode examples in Typescript and React. This isn’t a necessity for state machine driven UIs; however, having some familiarity with both would be helpful in reading and understanding this series.)</em></p><p>So, in the <a href="https://medium.com/@floyd.may/asyc-superpowers-state-machines-58abdf24aaa">last article</a>, I introduced you to state machines. Now, let’s see if we can take that knowledge and apply it to a real-world UI. Let’s say we’re building a UI that searches for <em>things</em>, and displays the things that match the search criteria. Here’s a sketch of what that might look like:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/660/1*0m-xyxJDidWLA_PZK2tCCQ.png" /><figcaption>Our UI</figcaption></figure><p>Now, let’s also say that we have to do some loading before we can display the above screen. We’ve got to load the available options for those dropdowns from the backend as well as the initial results, let’s say. Let’s also say that we have an “infinite scroll” type scenario, where we load another page of data when the user scrolls down far enough. So, we have four states of our UI. Our initial “loading” state:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/651/1*b0Pet-0l9TLUT8uN5hBTxg.png" /><figcaption>Let’s call this our “Loading” state</figcaption></figure><p>Next, our “loaded” state that shows results:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/660/1*0m-xyxJDidWLA_PZK2tCCQ.png" /><figcaption>The “Loaded” state of the UI</figcaption></figure><p>Third, we have a state that we show when we’ve changed our search criteria and are reloading results:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/663/1*Td33WKcgPRboZXm64zSgzA.png" /><figcaption>The “Reloading” state</figcaption></figure><p>And finally, our “loading more” state that we enter when the “infinite scroll” kicks in and we load another page of results:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/651/1*x3kGw9UF6WOiPKZZRAslmA.png" /><figcaption>The “Loading more” state</figcaption></figure><p>As you may have noticed, I’ve modeled every possible <em>state</em> that this UI could be in. As you might suspect, these will all correspond to states in a state machine. What you may have also noticed is that I’ve modeled states not just for when the UI is loaded, but for the various situations where the UI is waiting for data to load.</p><h3>State Data</h3><p>In order for this UI to display itself properly, it needs data. For all but the “Loading” state, the UI needs the list of things and the dropdown options. If we were to define that in code, it might look like this:</p><pre>type ThingSearchData = {<br>  things: Thing[];<br>  options1: Options[];<br>  options2: Options[];<br>  options3: Options[];<br>  searchText: string;<br>  selected1: string;<br>  selected2: string;<br>  selected3: string;<br>}</pre><p>However, the UI displays differently depending on which state it’s in. In Typescript, I tend to represent the states and their data as a “tagged” union type¹, like this:</p><pre>type Tagged&lt;T extends string&gt; = { tag: T };</pre><pre>type Loading = Tagged&lt;&quot;Loading&quot;&gt;;<br>type Loaded = Tagged&lt;&quot;Loaded&quot;&gt; &amp; ThingSearchData;<br>type Reloading = Tagged&lt;&quot;Reloading&quot;&gt; &amp; ThingSearchData;<br>type LoadingMore = Tagged&lt;&quot;LoadingMore&quot;&gt; &amp; ThingSearchData;</pre><pre>type State = Loading | Loaded | Reloading | LoadingMore;</pre><p>This lets us write code that accepts a State and then inspect it to see which state it is using typescript’s “<a href="https://www.typescriptlang.org/docs/handbook/2/narrowing.html">narrowing</a>”:</p><pre>if(state.tag === &quot;Loading&quot;) {<br>  renderLoading(state);<br>} else if(state.tag === &quot;Loaded&quot;) {<br>  renderLoaded(state);<br>} // and so on...</pre><p><em>(Quick note: you could use a class hierarchy in a language like C# or Java to accomplish the same goal of representing your states’ data. This isn’t a Typescript only concept!)</em></p><p>With our State type, we can now write some tests for our UI to make sure it displays itself properly given the right state. For example:</p><pre>describe(&quot;Loaded state&quot;, () =&gt; {<br>  const state = {<br>    tag: &quot;Loaded&quot;,<br>    things: [<br>      { name: &quot;A thing&quot; },<br>      { name: &quot;Another thing&quot; },<br>      { name: &quot;yet another thing&quot; },<br>    ],<br>    options1: [{ /* omitted for brevity */ }],<br>    /* and so on... */<br>  };</pre><pre>  beforeEach(() =&gt; {<br>    render(&lt;ThingSearch state={state} /&gt;);<br>  });</pre><pre>  it(&quot;should not show spinner&quot;, () =&gt; {<br>    expect(document.querySelectorAll(&quot;.spinner&quot;)).toHaveLength(0);<br>  });</pre><pre>  state.things.forEach(thing =&gt; {<br>    expect(screen.getByText(thing.name)).toBeInTheDocument();<br>  });<br>});</pre><p>So, we’ve solved one part of the problem: given a state, what should get displayed. We’ve also got a testing strategy for that. However, we still a few more details to sort through.</p><h3>Input and Actions</h3><p>Now, let’s examine, in our UI, what <em>user input</em> we need to handle. There are two distinct user interactions that we need to be concerned with:</p><ul><li>Search criteria changed — this occurs when the user changes the search text or any of the dropdowns. This will (eventually) lead to loading a new list of things.</li><li>Scrolled to bottom — this occurs when the user scrolls the page to the bottom, triggering the “infinite scroll” behavior that loads more data as the user scrolls.</li></ul><p>For the remainder of these articles, we’ll call these state machine inputs <em>actions</em>. We’ll also define some more actions for our UI’s state machine, but for now, let’s focus on these two. We need to represent these in code, and we’ll use a similar definition to our State type earlier:</p><pre>type SearchCriteriaChanged = Tagged&lt;&quot;SearchCriteriaChanged&quot;&gt; &amp; {<br>  searchText: string;<br>  option1: string;<br>  option2: string;<br>  option3: string;<br>}<br>type ScrolledToBottom = Tagged&lt;&quot;ScrolledToBottom&quot;&gt;</pre><pre>type Action = SearchCriteriaChanged | ScrolledToBottom;</pre><p>Given these definitions, we can now test that our UI properly produces the actions it should as the user types, clicks, and scrolls. For instance:</p><pre>it(&quot;Dispatches ScrolledToBottom action&quot;, () =&gt; {<br>  const actions: Action[] = [];<br>  render(&lt;ThingSearch<br>    state={loadedState}<br>    dispatch={a =&gt; actions.push(a)}<br>  /&gt;);</pre><pre>const container = document.querySelector(&quot;.thing-list&quot;);<br>  fireEvent.scroll(container, { target: { scrollY: 1000 } });</pre><pre>  expect(actions).toEqual([{<br>    tag: &quot;ScrolledToBottom&quot;,<br>  }]);<br>});</pre><h3>Writing the State Machine</h3><p>So far, we have a UI that displays itself properly based on its state, and the UI produces <em>actions</em> based on user input. However, we still don’t yet have code that allows us to move from state to state based on those actions. So, let’s discuss how to represent a state machine in code. Our UI’s state diagram should look something like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/691/1*xtJMZNlqHBpjApg1sU4mKg.png" /></figure><p>In the previous article, I said that transitions between states are labeled with the <em>input</em> that’s being processed by that transition. In the parsing examples, for instance, that input was letters. In the rollercoaster example, the input fell into two categories: button presses by the operator (open gates, close gates, launch, release restraints), and sensor input (coaster arrived). Similarly, our UI also has two categories of input, or, more precisely, two categories of <em>actions</em>. Our first category is <strong>user input</strong>. scrolled to bottom and search criteria changed are the direct user interactions that our state machine accepts. We also have another kind of action: <strong>asynchronous results</strong>; that is, stuff that is likely obtained via a fetch(...) call or similar. I’ve represented the transitions for those actions using dashed lines.</p><p>A key element in the design of this state machine is that <strong>we have states that represent when asynchronous things are pending</strong>. This is the core idea that lets us turn the complicated and difficult-to-test messiness of asynchronous operations into a straightforward, easy-to-test state machine. We can represent the data that gets returned from our asynchronous operations as our state machine’s <em>actions</em>, and prove that the machine transitions correctly given an action. For instance, our AdditionalDataLoaded action would probably be defined like this:</p><pre>export type AdditionalDataLoaded = Tagged&lt;&quot;AddlDataLoaded&quot;&gt; &amp; {<br>  things: Thing[];<br>}</pre><p>In the previous article I said that a state machine decides, given a current state and an action, what the next state should be. In code, this is a function whose signature looks like this:</p><pre>(state: State, action: Action) =&gt; State</pre><p>So, given one of our states and some action, we should be able to compute another state. This kind of function is called a <em>reducer</em>, and reducers typically take the form of nested switch statements or if/else chains:</p><pre>function reduce(state: State, action: Action): State {<br>  if(state.tag === &quot;Loading&quot;) {<br>    return reduceLoading(state, action);<br>  } else if(state.tag === &quot;Loaded&quot;) {<br>    return reduceLoaded(state, action);<br>  } // and so on</pre><pre>return state;<br>}</pre><pre>function reduceLoading(state: Loading, action: Action): State {<br>  if(action.tag === &quot;DataLoaded&quot;) {<br>    return {<br>      things: action.things,<br>      options1: action.options1,<br>      options2: action.options2,<br>      options3: action.options3,<br>      tag: &quot;Loaded&quot;,<br>    };<br>  }<br>  return state;<br>}</pre><pre>// additional reduceXXX functions omitted for brevity</pre><p>Given a state machine expressed as States, Actions, and a reducer function, putting the state machine under test is very straightforward. For example, here are some tests for the Loading state:</p><pre>describe(&quot;Loading state&quot;, () =&gt; {<br>  const state = { tag: &quot;Loading&quot; };<br>  it(&quot;ignores irrelevant action&quot;, () =&gt; {<br>    const result = reduce(state, { tag: &quot;ScrolledToBottom&quot; });<br>    expect(result).toEqual(state);<br>  });</pre><pre>it(&quot;transitions to Loaded on DataLoaded action&quot;, () =&gt; {<br>    const action = {<br>      things: [{ name: &quot;Thing 1&quot; }],<br>      options1: [{ label: &quot;Opt1 label&quot;, value: &quot;1&quot;],<br>      options2: [],<br>      options3: [],<br>    };<br>    const result = reduce(state, action);</pre><pre>    expect(result).toEqual({<br>      ...action,<br>      tag: &quot;Loaded&quot;,<br>    });<br>  });<br>});</pre><h3>Next Up: Putting It All Together</h3><p>We’ve solved quite a few problems up to this point, including writing tests for each:</p><ol><li>The UI displays properly given some State</li><li>The UI produces the right Action from user input</li><li>The state machine’s reducer function generates the correct next State given a current State and an Action</li></ol><p>However, we still have two important problems left to solve:</p><ol><li>Connecting the UI to a working state machine</li><li>Making the asynchronous calls at the right time, dispatching Actions when they complete</li></ol><p>In the <a href="https://medium.com/@floyd.may/async-superpowers-part-3-ac740bd84177">next article</a>, we’ll see how to connect all of this together so that our UI functions properly end-to-end.</p><p><strong>Footnotes</strong></p><p>[1]: <em>The </em><em>Tagged&lt;T&gt; type and its “tag” property is inspired by my distaste for the fact that Typescript doesn’t support </em><a href="https://en.wikipedia.org/wiki/Tagged_union"><em>tagged unions</em></a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1c55b04128fe" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Async Superpowers: State Machines]]></title>
            <link>https://medium.com/@floyd.may/asyc-superpowers-state-machines-58abdf24aaa?source=rss-aa761b7e3c3------2</link>
            <guid isPermaLink="false">https://medium.com/p/58abdf24aaa</guid>
            <category><![CDATA[ui]]></category>
            <category><![CDATA[computer-science]]></category>
            <category><![CDATA[unit-testing]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[Floyd May]]></dc:creator>
            <pubDate>Wed, 29 Dec 2021 20:25:49 GMT</pubDate>
            <atom:updated>2022-04-14T14:27:43.458Z</atom:updated>
            <content:encoded><![CDATA[<p>It seems that every UI in existence has to deal with doing something asynchronous. If you don’t know what that means, think back to every time you’ve seen one of these:</p><figure><img alt="A spinning “loading” indicator" src="https://cdn-images-1.medium.com/max/555/1*Po9xp9__sZ1DqytXswynDw.gif" /><figcaption>Hang on, we’re loading stuff…</figcaption></figure><p>Any time you see a “spinner” like the above, it’s probably an indication that some asynchronous stuff is happening. Programming UIs that do asynchronous stuff can be difficult. What often seems even <em>more</em> difficult is <strong>testing</strong> those UIs. And when I say, “testing,” I mean <em>real tests. </em>Automated tests. And… many programmers just don’t bother with those. Instead, we just slap some spinners into the code, do a bit of manual testing (ewww… 🤢), and call it good. I’m here to tell you, there’s a better way. A way to write UIs with complex asynchronous logic that you can test <em>easily</em>.</p><p>But, to get there, I’ve got to teach you some computer science fundamentals. So buckle up, we’re going to learn about <em>state machines</em>, also called <em>discrete finite automata</em> or <em>DFAs</em>.</p><h3>Part 1: Intro to State Machines</h3><p>A state machine is a way to model a specific kind of computation problem. It can be a system that changes over time, parsing text a character at a time, or a number of other kinds of similar problems. We can model each phase of that computation over time in precise steps, called <em>states</em>, and then define how the system moves from one state to another using something called <em>transitions</em>. So… <strong>states</strong> and <strong>transitions</strong>.</p><p>Let’s look at an example. Let’s say that we need to figure out if a given string is the string “ab”, that is, a single “a” followed by a single “b”. We can model this using a state machine that looks like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/379/1*qJfIvwsgChWGsPje9uSibw.png" /><figcaption>A simple state machine for parsing the string “ab”</figcaption></figure><p>You see, the way a state machine works is simply this: <strong>Given a current state and some input, a state machine decides what the next state is.</strong> Our states, start, s1, ands2, are represented by circles, and our transitions are the arrows that point between these three states. Notice that each transition has a letter associated with it. This is our input. One last observation is that s2 is marked green, to indicate that it’s our “success” state. Now, we’ll go through a few examples.</p><p>First, let’s try the string “ab”. We begin at the start state, and follow the transition from start to s1 for input a, arriving at s1. Then, at state s1, we follow the transition to s2 for input b. Since we’ve processed all the input and arrived at the “success” state, the state machine has shown us that this, indeed, is the string “ab”. Underwhelmed? Just hang in there.</p><p>Now, let’s see what happens when we give it input that doesn’t match. For instance, if we tried the string “ac”, we’d go from start to state s1, and then have input c that we need to process. <strong>But there is no transition from state </strong><strong>s1 for input </strong><strong>c. </strong>Put another way, there’s no arrow that starts at state s1 that is labeled with the input c. When we arrive at a state where there’s no transition away from that state for whatever input we’re looking at, the machine is “stuck”. When a state machine is stuck for a parsing problem like this, it means that the state machine is telling us “this input doesn’t match what I expect.”</p><p>Let’s try another failing example. Let’s parse the string “a” using our state machine. Again, we follow the transition for a from start to s1, but then we have no more input to process. The state machine is done processing the input, but it’s not at the “success” state of s2. This, again, means the state machine has told us that the input string we processed doesn’t match.</p><p>Now, let’s look at a more complex example:</p><blockquote>Zero or more ‘a’s followed by zero or more ‘b’s followed by at least one ‘c’.</blockquote><p>We can design a state machine¹ that solves this problem, and it looks like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/697/1*DXFRX_4QcVJXgV8mBfa-kg.png" /><figcaption>A <em>state diagram for parsing the string with the above rules.</em></figcaption></figure><p>This state machine is, obviously, a bit more complex. Let’s go through some examples. See if you can follow along from state to state as the machine processes each letter. First, let’s look at the steps for processing string “abbbc”:</p><ul><li>At state start, input a: follow transition for ato s1</li><li>At state s1, input b: follow transition for b to s2</li><li>At state s2, input b: follow transition for b to s2<br><em>Note: some transitions start and end at the same state, like this one. This is one of the ways that state machines can handle repetitive input.</em></li><li>At state s2, input b: follow transition for b to s2</li><li>At state s2, input c: follow transition for c to s3</li><li>At state s3, no remaining input: s3 is a success state; <strong>SUCCESS</strong></li></ul><p>Now, let’s look at the string “acd”:</p><ul><li>At state start, input a: follow transition for ato s1</li><li>At state s1, input c: follow transition for c to s3</li><li>At state s3, input d: no transition from s3 for d; stuck; <strong>FAIL</strong></li></ul><p>Now, try a few examples of your own that match the rules:</p><blockquote>Zero or more ‘a’s followed by zero or more ‘b’s followed by at least one ‘c’.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*iKiE_LhHurC5mHU5.jpg" /></figure><h4>More Than Parsing</h4><p>State machines can model more things than just parsing text. Let’s say we’d like to model the operational controls for a rollercoaster using a state machine. We have gates that allow the queued passengers into the loading area, we have restraints that keep people in the cars while the rollercoaster is moving, and we have a launch motor that gets the stopped rollercoaster moving onto the track. We also have a number of safety-related scenarios that we want to prevent:</p><ul><li>Open gates while the rollercoaster is moving — this could cause crowding near the loading platform and allow someone to be struck by a moving coaster</li><li>Restraints released while the rollercoaster is in motion — this could cause someone to fall out of the ride!</li><li>Open gates while the previous riders are still restrained and waiting to exit — this could cause sneaky passengers to ride multiple times in a row</li></ul><p>So, we could model the operational controls like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MTg7cHpymEJQ_Ur4u8CXVg.png" /><figcaption>A potential model for safe operation of a rollercoaster.</figcaption></figure><p>Starting with an empty rollercoaster with open gates (the Loading state), the operator ensures that passengers get seated and no other passengers are on the loading platform. Next, the operator closes the gates and begins securing the passengers (the Securing state). Once the passengers are secured, the operator launches the rollercoaster and the passengers enjoy their ride (the Riding state). When the coaster returns to the loading platform a sensor is triggered (the Waiting for exit state). The operator can then release the restraints (moving to the Exiting state) and wait for the platform to clear before opening the gates and allowing a new set of passengers to board (moving back to Loading). We also have the additional option while in the Securing state to release the restraints and let terrified would-be passengers out of the ride at the last moment. Don’t ask me why I know this is a thing.</p><p>If you remember, the transitions between states represent input, and state machines only accept certain inputs at certain states. For instance, this state machine only accepts the input Release restraints in the Waiting for exit and Securing states, since it would be obviously dangerous to release the restraints on a moving rollercoaster! If the operator were to press the “release restraints” button while the coaster is moving, the state machine would not become “stuck” like parsing strings. Instead, the state machine would simply ignore that input. So, in cases like parsing, state machines are “stuck” on unexpected input. In cases like safety controls and UIs, state machines often ignore invalid or irrelevant input.</p><h4>Next Up</h4><p>So, what do rollercoaster rides have to do with UIs that do asynchronous things? They both have to wait for things to finish, accept user input, and ignore invalid input. In the next few articles, we’ll talk through how to model a UI that does asynchronous stuff using a state machine. Next up: <a href="https://medium.com/@floyd.may/async-superpowers-part-2-1c55b04128fe">Part 2</a>!</p><p>¹ Fun fact: many regular expression engines use DFAs to parse strings, and there is a <a href="https://en.wikipedia.org/wiki/Regular_language">mathematical relationship</a> between DFAs and the kinds of strings that regular expressions can parse.</p><p><a href="https://gameprogrammingpatterns.com/state.html">For further reading</a>: great examples of why a state machine would be better than a big pile of if/else statements</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=58abdf24aaa" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Time Parsing — A Kata]]></title>
            <link>https://medium.com/@floyd.may/time-parsing-a-kata-1d88c3741c1a?source=rss-aa761b7e3c3------2</link>
            <guid isPermaLink="false">https://medium.com/p/1d88c3741c1a</guid>
            <category><![CDATA[coding]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[tdd]]></category>
            <dc:creator><![CDATA[Floyd May]]></dc:creator>
            <pubDate>Wed, 22 Sep 2021 21:18:49 GMT</pubDate>
            <atom:updated>2021-09-22T21:18:49.308Z</atom:updated>
            <content:encoded><![CDATA[<h3>Time Parsing — A Kata</h3><p>In building an app for one of my clients, my colleague and I stumbled across an interesting programming problem. I’ve rarely been happy with “time picker” widgets for the desktop, so we settled on just simple text entry. Type in “11:30” and it will interpret that as 11:30am. Type in 1130, and it will interpret it just the same. Type in “potato” and, of course, it will consider that invalid input. So, I present to you:</p><h3>The Time Parsing Kata</h3><p>Your task is to write and test a function that accepts a string, and returns either an object containing hours and minutes or some kind of null value. Hours will be from 0 to 23, minutes from 0 to 59. Specifications are at the bottom of this article.</p><p>What’s interesting about this particular task is that you can use this as a great tool to learn and solidify basic regular expression usage. This is a <em>painful</em> exercise without them. As you layer on bit by bit of complexity, regexes’ power becomes more and more obvious. You could, of course, get fancy and use a parser library of some kind, but regex will certainly do the job.</p><p>This kata also allows you to learn and experiment with fail-fast algorithm design. When something may or may not succeed, you have to design your algorithms differently.</p><p>I found this kata extremely useful as a tool in helping my colleague learn a bit about parsing, identifying and rejecting bad input, and writing clean code. Hope it’s helpful to you too!</p><h4>Specifications:</h4><ul><li>Single-digit numbers are parsed as the hour corresponding to the number. “8” is interpreted as 8:00am, for instance.</li><li>“10” and “11” are parsed as 10:00am and 11:00am respectively.</li><li>“12” is parsed as 12:00pm (noon).</li><li>An “a” or “am” suffix (with or without a leading space) ensures that the time is within the first twelve hours of the day; i.e. “12a” would be interpreted as 12:00am (midnight)</li><li>A “p” or “pm” suffix (with or without a leading space) ensures that the time is within the second twelve hours of the day; i.e. after noon</li><li>Two-digit numbers greater than 12 are assumed to be in 24-hour time notation; e.g. “13” is interpreted as 1:00pm.</li><li>Hours greater than 23 are treated as invalid.</li><li>Hours greater than 12 followed by either an “am” or “pm” (or its variants) are treated as invalid.</li><li>Hours may be followed by a colon and <em>exactly</em> two digits in the range “00” to “59”, corresponding to the number of minutes.</li><li>The colon may be omitted, but all the previous rules must still apply.</li><li>Leading or trailing whitespace is ignored.</li><li>Other characters are considered invalid and cause the entire string to be considered invalid.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1d88c3741c1a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Rules for Microservice Boundaries]]></title>
            <link>https://medium.com/@floyd.may/rules-for-microservice-boundaries-325ea633db38?source=rss-aa761b7e3c3------2</link>
            <guid isPermaLink="false">https://medium.com/p/325ea633db38</guid>
            <category><![CDATA[microservices]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Floyd May]]></dc:creator>
            <pubDate>Fri, 28 May 2021 15:58:28 GMT</pubDate>
            <atom:updated>2021-06-25T15:01:29.449Z</atom:updated>
            <content:encoded><![CDATA[<p>I continue to encounter highly-opinionated discussions about how to divide some problem space into microservices. I’ve seen multiple assertions that there is A Right Way™ to do this. (*sigh*) We need to talk.</p><p>First, y’all, let’s get this thing right out into the open. <strong>You’ve got to have high technical, operational, and organizational capability to do microservices well.</strong> I go into a lot of detail <a href="https://app.pluralsight.com/course-player?clipId=4ee0a618-a212-420d-a972-c34233443eb2">in the last module of my Pluralsight course</a> about what specific things you’ve got to have right before you even <em>consider</em> microservices. They’re <em>hard</em>. They cost a lot in complexity, and you’d better be sure that your non-programmer stakeholders are bought in on why you’re doing them and that <em>they</em> believe in the value that they’re delivering, because they’re <em>expensive</em>. And you’d better be <em>good</em> at code. And automation. And communication. And operational support.</p><p>Next, let’s talk about why you’d use microservices. They’re best used to solve one or more of these three issues:</p><ol><li>Scale: you’ve got a lot of users, or a lot of data, or a lot of processing to do</li><li>Complexity: you’ve got so much intricate logic that the additional cost of the service-to-service communications is dwarfed by the benefits of infrastructure-level decoupling</li><li>Governance: you have strict rules (like auditing or access control) that you are required to follow, and those rules may be different for different scenarios</li></ol><p>In simpler terms, you’ve got <em>a big honkin’ app</em> that may benefit from infrastructure-level decoupling. Bear in mind that this is different from just plain old decoupling. If you can’t manage decoupling in a monolithic app, microservices will not save you. Imma say that again:</p><blockquote>If you can’t manage decoupling in a monolithic app,<br><strong>microservices will not save you.</strong></blockquote><p>You see, depending on what kind of problem you’re trying to solve, you’ll use different criteria to decide how to split up functionality into different microservices. If you’re solving a scale problem, this may be separating commands and queries (a la <a href="https://martinfowler.com/bliki/CQRS.html">CQRS</a>) or teasing apart slow operations from quick ones. If you’re solving complexity problems, it may be that a DDD-oriented approach (bounded contexts, aggregates, and so on) might be helpful. If you’re solving a governance problem, a façade or a gateway might be appropriate. There are so many different patterns to choose from, and the right choice requires a balanced evaluation of the entire situation.</p><p>Making microservice architecture choices, much like many other kinds of software design choices, requires experience and judgment. With microservices in particular, it’s easy to destroy performance or to create an unmanageable mess. Complexity is costly, and there is an entire world of complexity that microservices introduce. That complexity isn’t just in code and API definitions. It also encompasses organizational communication, security, observability, maintainability, SLOs/SLAs, and ROI, just to name a few things. It will likely also encompass things that are unique to your particular scenario. Never forget: building it isn’t enough. You have to support it running in the real world.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*0ZsyG8iMw6lXPEDl.jpeg" /><figcaption>There is no rule.</figcaption></figure><h4>TL; DR</h4><p>Avoid blindly following hard-and-fast rules about how to divide up a solution into microservices. Microservices are hard; mostly, because they require high capabilities across many disciplines. Since effective microservice implementations require balanced decision making and judgment that factors in many details, rules are likely to cause more harm than good.</p><p>For more information, check out <a href="https://app.pluralsight.com/library/courses/getting-started-microservices/table-of-contents">my Microservices: Getting Started Pluralsight course</a>. If you need some help, <a href="https://canyon-trail.com/">reach out to me</a>!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=325ea633db38" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How to Get Cox to Fix Your Internet]]></title>
            <link>https://medium.com/@floyd.may/how-to-get-cox-to-fix-your-internet-b1e5950075a4?source=rss-aa761b7e3c3------2</link>
            <guid isPermaLink="false">https://medium.com/p/b1e5950075a4</guid>
            <category><![CDATA[technical-support]]></category>
            <category><![CDATA[internet-service-provider]]></category>
            <dc:creator><![CDATA[Floyd May]]></dc:creator>
            <pubDate>Thu, 15 Apr 2021 15:27:35 GMT</pubDate>
            <atom:updated>2021-04-15T15:27:35.268Z</atom:updated>
            <content:encoded><![CDATA[<p>I recently went through a miserable bout of tech support nonsense with my cable internet provider, Cox. Right around Friday, February 5, I started seeing my internet connectivity drop completely for spurts of up to 2 or 3 minutes. This affected my laptop, our phones, our tablets, our TV streaming devices, everything. Others in my neighborhood’s Facebook group complained about similar issues starting around the same time. This was Super Bowl weekend, so I chalked it up to a temporary problem, and thought little of it. It continued throughout the weekend, so I reached out to Cox the following Monday to get help. I used the “live chat” feature, since it was a workday and I was also attempting to get work done at the same time. The first tech support person dutifully followed their script, and discovered that, unsurprisingly, the problem was not solved after doing so. They then escalated me to a “supervisor.” This person lied to me multiple times, and I have the transcript to prove it. After suffering through their incompetence, I finally agreed to a technician visit.</p><blockquote>This person lied to me multiple times, and I have the transcript to prove it.</blockquote><p>They sent a tech out the following day. Meanwhile, my conference calls were almost unusable, and I had to resort to tethering to my phone’s mobile hotspot in order to do my job, which requires frequent conference calls. The tech monitored the feed to my house, inspected all my cables and informed me that everything he could check indicated that nothing was wrong. The tech also empathized with my situation, and acknowledged that, despite his diagnostics, there was likely still a problem that he had no authority to solve. He recommended gathering data for a few days and contacting Cox after having enough data to demonstrate a real problem.</p><p>I wrote a crude little ICMP monitoring script. Bear in mind, this is not the kind of thing that a typical Cox customer would have the knowledge or skill to do. I happen to have experience in both software development and network management. With this monitoring in place, I discovered that I frequently had packet loss above 1%, and often had packet loss above 25%. For reference, 1–2% packet loss is “noticeable,” and packet loss above 5% makes most internet usage almost impossible. My wifi router also registered what it called “DoS attacks” that coincided with periods of poor connectivity. With this data, I reached back out to Cox on Wednesday, February 10 with my intermediate findings.</p><blockquote>They apparently take it seriously when the FCC gets involved.</blockquote><p>At this point, I was forwarded to Cox’s internet abuse department. This department opened a ticket, and summarily closed it the following day with no action taken, and my connectivity still insufferably bad. I had to call back multiple times per day from Wednesday the 10th through Friday the 12th. Nobody proactively called me, multiple people promised callbacks that never occurred, my internet was still broken, and nobody did anything about it. With both my connectivity disrupted as well as my router registering DoS attacks, I took to social media to see if I could get some traction via another means. Bear in mind, at that point I’d had six different conversations with Cox and nobody was able to do anything about this very real problem. <br> <br>Upon the <a href="https://twitter.com/ChaseAucoin/status/1360274947508174856">recommendation</a> of a friend, I reached out to the FCC. This put me (FINALLY!) in touch with the executive escalations department at Cox. They apparently take it seriously when the FCC gets involved. By this time I had bolstered the functionality of my monitoring script so that I could see, in real time, when packet loss was occurring. A dot represented a successful test, an X, a failed test. Screenshots of this tool facilitated commiseration with my colleagues when my connectivity dropped out:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/347/1*A7fECbhQcNmI1CWRz_Ukug.png" /><figcaption>Dots represent successful tests; ‘X’ represents a fail. Naturally, “Floyd’s getting Xes!” meant that my connectivity was failing and I was about to drop out of a conference call.</figcaption></figure><p>I had also improved the analysis and visualization of the connectivity data I was gathering:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/539/1*0-Rhx8RpawDviwatv5Zc1g.png" /><figcaption>Anything above 1% is noticeable, and above 25% makes internet usage almost impossible.</figcaption></figure><p>Thankfully, the person at Cox’s executive escalations department was knowledgeable, empathetic, and tenacious. She corresponded repeatedly with many different internal departments at Cox. However, she, like me, was unable to get anyone to do anything, or to even acknowledge that a problem existed. I also bought and configured a new wifi router just to eliminate a potential problem. No change. After dozens of emails back and forth, we finally got a field engineer to examine the issue. They came to my house on February 26, and, like the first tech, claimed they could see no issues. They said they’d email the network engineer, and disappeared. Problems still happening. By this time, this issue had been ongoing for three weeks, and I had accumulated over $100 in data overages on my mobile phone due to tethering, as well as the expense of the new wifi router. Then, my packet loss disappeared the following day, Saturday, Feb 27, around 7pm:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/841/1*OlQtyApVrceX40pds0R-Qw.png" /><figcaption>By this time, I had so much data that I couldn’t graph it per-minute, so they’re bucketed to 10 minutes. Notice on the far right that the red bars disappear abruptly.</figcaption></figure><p>After reaching back out to the saint at executive escalations (bless her heart, she worked so hard to help me!), she told me that she couldn’t find any evidence of anyone actually changing anything. However, the problem is still mysteriously solved, for now. What concerns me is that clearly someone at Cox changed something, but nobody seemed willing to own up that something has changed.</p><p>I did later receive a letter from Cox in reference to the FCC complaint. Here is an excerpt:</p><blockquote>After our Executive Escalations team member first spoke with you on February 15, 2021, one of our technicians had visited your home on February 9, 2021 and again on February 27, 2021. During the first field visit no packet loss was measured. Subsequently, your contact with technical supervisors determined<br>there was packet loss measured using our desktop tools. On February 27, 2021 a network field technician measured trace routes multiple times for 20,000 pings with no packet loss. The network technician was unable to review the previous tickets submitted and determined they were closed to lack of findings. We<br>had our communications center check for firmware updates which were current and determined we needed to perform some work on our network to address your concerns.</blockquote><p>“[W]e needed to perform some work on our network.” Interesting. What I’ve now learned is that another person in my neighborhood is now experiencing similar problems. They’re not an experienced software developer with network management experience, so it’ll be <em>even more difficult</em> for them to get resolved if they’re experiencing the same problem. I have no help to offer to my neighbor to help them through Cox’s tech support maze. The best information I’ve gotten is “we needed to perform some work on our network.”</p><p>Through this entire ordeal, I’ve learned a few things about Cox:</p><ol><li>Their tech support processes are designed so that support personnel are incentivized to close tickets as quickly as possible. There is no accountability for having actually solved a problem when a ticket is closed, so it’s very likely that support tickets will be closed without any action and without any follow-up.</li><li>Cox’s technical support is under-trained (at best) and is willfully deceitful (at worst). I had multiple Cox representatives lie to me and misrepresent themselves as having knowledge that they didn’t actually have.</li><li>Cox’s departmental siloing ensures that following a customer’s issue through to completion is nigh impossible. Even with an executive resolution specialist representing me, tireless followup and retrying was essential. Thankfully she handled most of that once I got in contact with her, but she encountered the same problems I did; namely, tickets getting closed with no action and no follow-through, with each closure stating something to the effect of “this got sent to the wrong department.”</li><li>Cox isn’t monitoring their customers’ network access beyond physical connectivity. This kind of connectivity problem is likely very detectable from their equipment, and should be getting proactively monitored. It shouldn’t require a software developer/network engineer, dozens of tech support calls, and an FCC complaint for Cox to observe, acknowledge, and fix this kind of problem.</li><li>It takes the threat of regulatory action from the FCC for Cox to put real resources onto solving a problem that doesn’t easily fit into their tech support scripts. <br> <br>I’ll finish up with a huge thank you to my executive escalation specialist, without whom, I have no idea how much more nonsense I would have had to wade through to get Cox to fix my issue. She inspired me to write this, in part, to help her communicate internally at Cox to fix some of these things, and also, to help shed some public light on this so that Cox will be more motivated to fix their internal politics and make true on their platitudinous claim of “we care about our customers.”</li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b1e5950075a4" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>