{"id":276,"date":"2026-11-19T13:03:35","date_gmt":"2026-11-19T13:03:35","guid":{"rendered":"https:\/\/jschuster.org\/blog\/?p=276"},"modified":"2026-11-19T13:03:36","modified_gmt":"2026-11-19T13:03:36","slug":"design-for-understandability","status":"publish","type":"post","link":"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/","title":{"rendered":"Design for Understandability"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\"><em>This is a talk I gave at Google&#8217;s internal Code Health Summit in November of 2025. I&#8217;m sharing it here in the hopes that it sparks further learning and discussion.<\/em><\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Abstract<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">In a world where LLMs generate much of our code, understanding that code is more important than ever. But with a system as large and complex as Google&#8217;s codebase, SWEs can easily fall into a pattern of learned helplessness where the best you can do is tweak the code and pray that it passes the tests. Without understanding, LLMs are little more than complexity-generating machines running at top speed.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">There&#8217;s a better way to go about this. Just as our industry has learned to design software for testability, we can also design it for understandability. We can use ideas like design by contract, class invariants, modularity, and more to create systems that we can understand one piece at a time, rather than piling more onto the big ball of mud and hoping it doesn&#8217;t all collapse.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Is it easy? No. But is it worthwhile? Absolutely. These ideas aren&#8217;t new, but they&#8217;re not nearly as widely taught or well understood as they deserve to be, and mastering them leads to a world where we can have more confidence in our code and increase velocity at the same time.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Slides and Transcript<\/h2>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_1-1024x576.png\" alt=\"\" class=\"wp-image-277\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_1-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_1-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_1-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_1.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Hi everyone, thanks for having me! Let&#8217;s get started.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_2-1024x576.png\" alt=\"\" class=\"wp-image-280\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_2-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_2-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_2-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_2.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">I\u2019d like to start this talk with a question: If LLMs can code, then what is left for human SWEs?<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The tech industry is quickly looking to large language models to write all of our code. But you might say: isn\u2019t writing code our job as software engineers? Where does this leave the responsibility of SWEs? What is the essential human element that SWEs add on top of LLMs?<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Every one of you is going to have a different answer to this question, and that\u2019s fine. But here\u2019s my take.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_3-1-1024x576.png\" alt=\"\" class=\"wp-image-364\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_3-1-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_3-1-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_3-1-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_3-1.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">That necessary human element is judgment. Judgment of whether the code is maintainable. Judgment of whether it is healthy.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">LLMs can follow patterns and generate code that looks like what it was trained on. Sometimes they can produce useful tips and critiques for a piece of code. But that critical piece of judgment, of deciding whether some code is suitable for the task it was designed for, is still up to you, the human.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_4-1024x576.png\" alt=\"\" class=\"wp-image-283\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_4-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_4-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_4-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_4.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Because here\u2019s the thing: LLMs today are still a sloppy intern. Sometimes the code they produce is good, but sometimes it\u2019s completely off-track and needs correcting. You wouldn\u2019t incorporate a sloppy intern\u2019s code into your system without a close review first, so you shouldn\u2019t do so for an LLM\u2019s code either.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_5-1024x576.png\" alt=\"\" class=\"wp-image-284\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_5-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_5-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_5-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_5.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">YOU are responsible for the quality of your code, regardless of whether you had an LLM generate it for you or wrote it the old-fashioned way with fingers on a keyboard<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_6-1024x576.png\" alt=\"\" class=\"wp-image-285\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_6-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_6-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_6-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_6.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">So where does that leave us? If LLMs are going to write a lot of the code for us, then we\u2019re looking at a future where we humans are going to spend less time writing code, and more time reading code and understanding it, in order to make sure it passes our quality bar.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">This means it\u2019s more important than ever to get better at understanding code, and to speed up that reading and understanding process.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Now: if you want to get better at something, it\u2019s helpful to set an aspirational goal for yourself. Something that\u2019s above your current skill level, and drives you to get better and better every day.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_7-1024x576.png\" alt=\"\" class=\"wp-image-286\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_7-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_7-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_7-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_7.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Here\u2019s the goal I propose: we should be able to predict the behavior of every line of code, without running a single test.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Let me say that again: We should be able to predict the behavior of every line of code, without running a single test<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_8-1024x576.png\" alt=\"\" class=\"wp-image-287\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_8-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_8-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_8-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_8.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Now, I know you may be thinking: &#8220;Understand every line of code? Without testing? Are you serious?! There\u2019s way too much complexity and legacy code for me to ever be able to do that!&#8221;<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">You might think so. And if we take our hands off the wheel and relinquish all control, you might be right. But I\u2019m here to tell you there\u2019s a better way.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_9-1024x576.png\" alt=\"\" class=\"wp-image-288\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_9-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_9-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_9-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_9.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">We can <em>design<\/em> our code to be understandable.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Consider that a decade or two ago, we used to think that writing multiple tests for every public method in an API would have been infeasible. It wasn\u2019t because we didn\u2019t want to, or that we weren\u2019t trying. It was because we hadn\u2019t designed our code to make testing possible at that level. But gradually, across the software industry, we changed our practices to design for testability. Today, designing our code for testability is so ingrained into our culture that doing anything else is practically unthinkable. We can do the same for understandability, so that our code enables us to understand it better.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_10-1024x576.png\" alt=\"\" class=\"wp-image-289\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_10-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_10-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_10-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_10.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Our own Code Health guide makes a strong case for understandability. It says &#8220;For code to be sustainable, it must be understood. Change cannot be made unless a developer knows what the system currently provides, and what needs to change to adapt to new circumstances. As a result, key components of code health include good documentation, easy to understand error messages, and clear, simple code&#8221;<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_11-1024x576.png\" alt=\"\" class=\"wp-image-290\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_11-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_11-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_11-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_11.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Not only is designing for understandability important, but it\u2019s a learnable skill. It\u2019s not some magical ability that you either have or you don\u2019t. There are specific, concrete actions you can take to improve the understandability of your code.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">I\u2019m going to introduce you to a few of those today. Think of it as a \u201cstarter kit\u201d for designing for understandability. We\u2019ll also talk more about a general theme that runs through all of these practices, so that at a certain point you can find even more ways to design your code for understandability.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The ideas I\u2019m going to show you today are not new. But they\u2019re not taught as well as they should be, when they\u2019re taught at all, and most of us have only a rough understanding of how to apply them. My goal today is to sharpen that understanding just a little bit, and make it just a little more practical, so we can kickstart a process of making our code more understandable over time.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_12-1024x576.png\" alt=\"\" class=\"wp-image-291\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_12-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_12-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_12-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_12.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">So let\u2019s get started on each of these Design for Understandability practices.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_13-1024x576.png\" alt=\"\" class=\"wp-image-292\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_13-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_13-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_13-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_13.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">The first one is Design by Contract.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_14-1024x576.png\" alt=\"\" class=\"wp-image-293\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_14-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_14-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_14-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_14.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">To motivate the idea, let\u2019s ask the question: when calling a method, what behavior should you rely on?<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Let\u2019s say we have this binary search method, but its documentation is not terribly helpful (you\u2019ve probably seen something like this before).<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Binary search is reasonably well understood, but as a caller of the method, we have some questions we want to ask about this specific implementation. Such as:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Will the returned index always be the first occurrence?<\/li>\n\n\n\n<li>What happens if t is not found?<\/li>\n\n\n\n<li>What happens if the list is not sorted?<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">The documentation doesn\u2019t answer these questions. So what can we do?<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">First, we could guess. But we\u2019ll probably be wrong.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Second, we could read the code. But that might take a long time, especially if the particular behavior we care about is buried several levels deep.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Third, we could test the code on some examples and see what happens. But just because it works a certain way on some examples doesn\u2019t necessarily mean it works that way for all such inputs. Furthermore, even if it works that way now, there\u2019s no guarantee that it will continue to work that way in the future.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_15-1024x576.png\" alt=\"\" class=\"wp-image-294\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_15-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_15-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_15-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_15.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">The point is that without a clear statement of what this code is intended to do, there\u2019s no distinction between implementation and intent. The SWE who wants to use this code has to guess at which behavior the method <em>commits<\/em> to, versus which behavior is an implementation detail that might change over time.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_16-1024x576.png\" alt=\"\" class=\"wp-image-295\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_16-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_16-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_16-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_16.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">This is where contracts come in.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">There are many ways to define a contract, but for the sake of this talk I\u2019m going to define it as a formal-ish description of the observable behavior that each participant in an interaction commits to.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_17-1024x576.png\" alt=\"\" class=\"wp-image-296\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_17-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_17-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_17-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_17.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">In the real world, a basic contract is something like \u201cIf I cook dinner, then you will wash the dishes\u201d.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">In programming, an example might be: \u201cIf the caller provides a non-negative integer n, then the square-root function returns the square root of n\u201d<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Let\u2019s see how contracts can help us with our binary-search example.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_18-1024x576.png\" alt=\"\" class=\"wp-image-297\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_18-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_18-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_18-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_18.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Here\u2019s a possible contract for this function. It says, &#8220;If the list is sorted, binarySearch returns the index of the first occurrence of t in the list, or -1 if not found. Behavior is undefined for unsorted lists.&#8221;<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">We can see that this contract answers the questions we asked about it:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Will the returned index always be the first occurrence? Yes, the contract explicitly says this.<\/li>\n\n\n\n<li>What happens if t is not found? The contract says binarySearch will return -1 to signal that case.<\/li>\n\n\n\n<li>What happens if the list is not sorted? The contract doesn&#8217;t say anything, so this behavior is intentionally left undefined. And that\u2019s a valid design choice! There may be performance reasons to not check whether the list is sorted at run-time. So this contract tells the user that they shouldn\u2019t rely on any particular behavior if the list is not sorted. Instead, the obligation is on the caller to check whether the list is sorted before calling binarySearch.<\/li>\n<\/ul>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_19-1024x576.png\" alt=\"\" class=\"wp-image-298\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_19-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_19-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_19-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_19.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">The power of a contract is that it defines a clear boundary between the author\u2019s intent and the implementation. The caller doesn\u2019t have to guess at the behavior anymore: they can just read the contract, and if a specific detail of the behavior isn\u2019t there, they will know that it\u2019s unspecified.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">In reality, this isn\u2019t always perfect. Whether intentionally or accidentally, we still tend to end up with code that relies on implementation details rather than specified behavior. But contracts at least give us a way to minimize this behavior.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_22-1024x576.png\" alt=\"\" class=\"wp-image-301\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_22-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_22-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_22-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_22.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Now that we understand what a contract looks like, let\u2019s talk about how contracts can help us reason about and understand our code better.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Suppose you just wrote a method. I\u2019m going to draw that method as a little circle here.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_23-1024x576.png\" alt=\"\" class=\"wp-image-302\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_23-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_23-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_23-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_23.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">You want to know if it\u2019s correct.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">I\u2019m going to use a purple circle to stand for methods we\u2019ve read the code for<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_24-1024x576.png\" alt=\"\" class=\"wp-image-303\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_24-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_24-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_24-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_24.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Now, our method doesn&#8217;t live in isolation: it calls some other code.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_25-1024x576.png\" alt=\"\" class=\"wp-image-304\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_25-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_25-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_25-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_25.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">So, you think &#8220;Okay, well, I need to understand what those do. I&#8217;m going to read the code for those methods.&#8221;<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_26-1024x576.png\" alt=\"\" class=\"wp-image-305\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_26-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_26-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_26-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_26.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Well, those methods call other methods, and we start thinking about this,&nbsp;and figure out how we&#8217;re going to reason about those. And at this point you can maybe see where I&#8217;m going.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_27-1024x576.png\" alt=\"\" class=\"wp-image-306\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_27-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_27-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_27-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_27.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Oh no. Now we have lots and lots of code we have to read across our entire code base.<\/p>\n\n\n\n<figure class=\"wp-block-image size-full presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"960\" height=\"540\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-1.png\" alt=\"\" class=\"wp-image-374\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-1.png 960w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-1-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-1-768x432.png 768w\" sizes=\"auto, (max-width: 960px) 100vw, 960px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Why do we need all this reasoning just to reason about one single method? That&#8217;s all we&#8217;re trying to do! How did we get so out of control?<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_29-1024x576.png\" alt=\"\" class=\"wp-image-308\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_29-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_29-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_29-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_29.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">So, let&#8217;s back up and try again, using Design by Contract this time.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_30-1024x576.png\" alt=\"\" class=\"wp-image-309\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_30-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_30-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_30-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_30.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">You still have to read your own code. We can&#8217;t get around this part; that&#8217;s the change we just made.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_31-1024x576.png\" alt=\"\" class=\"wp-image-310\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_31-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_31-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_31-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_31.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">And we haven&#8217;t changed the code. It still calls those other methods.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_32-1024x576.png\" alt=\"\" class=\"wp-image-311\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_32-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_32-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_32-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_32.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">But now, the trick is that we can read just the <em>contract<\/em> on those called methods, not the code.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">And that&#8217;s it! We can stop here. We don&#8217;t need to worry about all of that other code. The contracts tell us all we need to know about calling these other two methods.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_33-1024x576.png\" alt=\"\" class=\"wp-image-312\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_33-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_33-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_33-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_33.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">The rest of that code still exists, but we don&#8217;t have to think about it. The contract abstracts away all that other behavior that doesn&#8217;t matter to us as the caller of these two methods.<\/p>\n\n\n\n<figure class=\"wp-block-image size-full presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"960\" height=\"540\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-2.png\" alt=\"\" class=\"wp-image-375\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-2.png 960w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-2-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-2-768x432.png 768w\" sizes=\"auto, (max-width: 960px) 100vw, 960px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">So that is the power that contracts give to us to reason about our code.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_35-1024x576.png\" alt=\"\" class=\"wp-image-314\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_35-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_35-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_35-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_35.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Finally, I\u2019ll wrap up this section with a few tips for writing contracts:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">First, document the behavior that you\u2019re willing to commit to. This is usually the same as what you want your callers to rely on. For example, you probably want to document the return value of your method. But the exact human-readable text in your error messages? Not so much.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Second, describe your error handling in your contracts. A contract does not and should not be just about the happy path. If your method might go wrong in some way, tell the caller under what conditions it might go wrong, and how you\u2019re going to signal that to the caller, whether it be through a special return value, or an exception, or something else.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Finally, keep in mind that the more callers your method has, the harder it is to change the contract. If it\u2019s a private method used only by your team? Sure, that\u2019s probably an easy case to change both the contract and change the callers to match. If it\u2019s a public method on a popular framework used by hundreds of other projects? Then renegotiating the contract is a much more expensive effort, so you should evaluate the costs and benefits carefully before deciding to do that.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_36-1024x576.png\" alt=\"\" class=\"wp-image-315\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_36-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_36-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_36-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_36.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">So that was the first element in our Design for Understandability starter kit.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_37-1024x576.png\" alt=\"\" class=\"wp-image-316\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_37-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_37-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_37-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_37.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">The next one is data invariants.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_38-1024x576.png\" alt=\"\" class=\"wp-image-317\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_38-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_38-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_38-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_38.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Let me explain this idea with a little story.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Early in the COVID-19 pandemic, when my wife and I started working from home, we missed having free soda at work. So we got in the habit of keeping cans of Diet Coke in the fridge.<\/p>\n\n\n\n<figure class=\"wp-block-image size-full presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"960\" height=\"540\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-3.png\" alt=\"\" class=\"wp-image-376\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-3.png 960w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-3-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-3-768x432.png 768w\" sizes=\"auto, (max-width: 960px) 100vw, 960px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">But there was a problem: we were great at taking cans out of the fridge, but not so great about putting new ones back in. So if you\u2019re working hard and looking forward to taking a break with a nice cold beverage, it was a big disappointment to open a Coke-less fridge and resort to drinking room-temperature soda from the pantry instead.<\/p>\n\n\n\n<figure class=\"wp-block-image size-full presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"960\" height=\"540\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-4.png\" alt=\"\" class=\"wp-image-377\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-4.png 960w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-4-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/Design-for-Understandability-public-blog-post-version-4-768x432.png 768w\" sizes=\"auto, (max-width: 960px) 100vw, 960px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">The problem was that we hadn\u2019t set any rules on how we retrieve Diet Coke and how we replenish the fridge.&nbsp; Without any rules governing access to the fridge, we eventually got into an unwanted state: in this case, an empty fridge.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_41-1024x576.png\" alt=\"\" class=\"wp-image-320\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_41-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_41-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_41-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_41.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">This happens in code, too. For example, let\u2019s say you have this proto to represent a customer\u2019s order [Note: &#8220;proto&#8221; is Google jargon for a Protocol Buffers message, similar to a JSON object]. If you receive this proto, how much do you trust that the total actually indicates the total amount on the items?<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Probably not much, right? This proto could have come from any part of your code, so it\u2019s easy to imagine that someone forgot to set that field appropriately.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Protos give you completely uncontrolled access to the underlying representation of your data. Protos are great for transferring data back and forth across the network, but they\u2019re poorly suited to situations where you want to rule out certain states.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_42-1024x576.png\" alt=\"\" class=\"wp-image-321\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_42-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_42-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_42-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_42.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">To solve these kinds of problems, we can use data invariants. A data invariant is a statement about a piece of data that is always true.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Data invariants are a principled way to enforce these kinds of valid states in your data. If you use them well, you can avoid a lot of bugs in your code.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Let\u2019s see how we can use invariants to solve the Diet Coke problem, and similar problems you might come across in your own code<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_43-1024x576.png\" alt=\"\" class=\"wp-image-322\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_43-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_43-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_43-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_43.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">First, identify the invariant you want to maintain.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Ask yourself: What\u2019s the property you want to rely on for this piece of data? Where are the places in the code where you explicitly validate and return an error if invalid? Alternatively, where do you make the assumption that it\u2019s invalid, but you\u2019re not actually sure?<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">In this case, the invariant we want is \u201cthe fridge always contains a Diet Coke\u201d.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_44-1024x576.png\" alt=\"\" class=\"wp-image-323\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_44-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_44-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_44-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_44.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Second, you need to document the invariant.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">It\u2019s important to note this is a separate step. It\u2019s one thing to have an invariant in your own head. It\u2019s another thing to write it down so that you communicate it to everyone else who might touch this code. Not to mention that if you come back to this code months or years later, you yourself might have forgotten which exact invariant you meant to maintain.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Write it down where people will see it: probably close to the relevant data members, or maybe in a class-level comment at the top.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_45-1024x576.png\" alt=\"\" class=\"wp-image-324\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_45-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_45-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_45-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_45.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Third, establish the invariant at creation time. Usually this will be done in a constructor or factory method. In this case, we\u2019re constructing the fridge with a few drinks already added.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><a href=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_46.png\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_46-1024x576.png\" alt=\"\" class=\"wp-image-325\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_46-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_46-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_46-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_46.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/a><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Fourth, every time you change your the data, make sure you maintain the invariant.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">This is the part my wife and I didn\u2019t do for our fridge. What we should have done is established a rule where if you take a Diet Coke, you put another one back in the fridge to make sure there\u2019s another for the next person.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">You can maintain the invariant many ways &#8211; that part is up to you. The important thing is that you always maintain it. Without that, you have to think to yourself \u201cWait, are there going to be Diet Cokes in the fridge? Did I already take them out earlier? Let me go back and check all my callers to see if they did that already\u201d. With an invariant, though, you just know: If I have a Fridge object, then it definitely has Diet Cokes, regardless of the sequence of operations that led to this point.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_47-1024x576.png\" alt=\"\" class=\"wp-image-326\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_47-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_47-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_47-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_47.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Finally, one last step, and this might be the hardest one: you need to maintain the invariant as the code evolves. It\u2019s relatively easy to maintain the invariant for a single version of code. But over the weeks, months, and years, complexity will creep in, new requirements will force you to change the code, and you might accidentally break the invariant or forget you even had one.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Establish the culture on your team that maintaining invariants is just a thing you do. If you have a mental checklist of things you look for in code review, make sure that maintaining the invariants is on that checklist.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_48-1024x576.png\" alt=\"\" class=\"wp-image-327\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_48-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_48-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_48-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_48.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">So how do data invariants help us design for understandability? Let\u2019s first consider what we have to do when we don\u2019t have an invariant.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Recall this representation of all the methods in your codebase, calling each other in various ways. Suppose you have a proto-based version of the fridge, and you want to know if it has any Diet Cokes in it. Because it\u2019s a proto, you don\u2019t have a way of knowing what state it\u2019s in.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_49-1024x576.png\" alt=\"\" class=\"wp-image-328\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_49-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_49-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_49-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_49.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">So, you need to check all the callers of the current method.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_50-1024x576.png\" alt=\"\" class=\"wp-image-329\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_50-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_50-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_50-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_50.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">And you do the check, crawling across the codebase, and you find that there\u2019s one particular case where you didn\u2019t enforce it.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Of course you can fix these issues one at a time as they crop up, but all that searching sounds like a lot of work, right? What do you think are the chances you\u2019re always going to find that one particular buggy spot? What are the chances that new methods added to this web of code are going to maintain that condition?<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_51-1024x576.png\" alt=\"\" class=\"wp-image-330\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_51-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_51-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_51-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_51.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">In contrast, let\u2019s try the version with our Fridge class and its invariant.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_52-1024x576.png\" alt=\"\" class=\"wp-image-331\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_52-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_52-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_52-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_52.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">In this case, the class has an invariant: the Fridge always has at least one Diet Coke, no matter what operations have been done previously or where we came from. By maintaining that invariant, we\u2019ve removed the need to check what every single caller does.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">This is what data invariants do for you: they let you focus on the state you\u2019re in now, and not how you got there.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_53-1024x576.png\" alt=\"\" class=\"wp-image-332\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_53-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_53-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_53-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_53.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">That wraps up the section on data invariants.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_54-1024x576.png\" alt=\"\" class=\"wp-image-333\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_54-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_54-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_54-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_54.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">The final practice I want to discuss today is isolating side effects and dependencies on global state.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_55-1024x576.png\" alt=\"\" class=\"wp-image-334\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_55-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_55-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_55-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_55.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">To motivate this idea with an example. Let\u2019s say there\u2019s a supermarket point-of-sales system with this method to compute sales tax. Now ask yourself: what are the inputs and outputs for this method?<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_56-1024x576.png\" alt=\"\" class=\"wp-image-335\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_56-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_56-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_56-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_56.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Seems pretty obvious, right? It takes in a customer\u2019s grocery order and returns the sales tax as an integer.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_57-1024x576.png\" alt=\"\" class=\"wp-image-336\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_57-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_57-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_57-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_57.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">But that\u2019s not the whole story. If you dig into the implementation of this method, you\u2019ll find that it reads in a set of sales tax rates from a separate file. That\u2019s effectively a new input channel! The code depends on that data to compute the tax just as much as it depends on the content of the grocery order itself.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_58-1024x576.png\" alt=\"\" class=\"wp-image-337\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_58-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_58-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_58-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_58.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">And if you look further, you\u2019ll find that the method also records the computed tax in the store\u2019s account database for bookkeeping purposes. That\u2019s a new output, but it\u2019s nowhere to be found in the type signature!<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_59-1024x576.png\" alt=\"\" class=\"wp-image-338\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_59-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_59-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_59-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_59.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">So functions have two kinds of input and output: the ones that are visible in the type signature, like the order and the computed sales tax, and the ones that are hidden, like the tax rates file and the entry in the accounting database.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_60-1024x576.png\" alt=\"\" class=\"wp-image-339\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_60-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_60-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_60-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_60.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">The hidden outputs are more commonly known as side effects. Side effects generally come in two flavors: mutation, so modifying something like a global variable or one of your input arguments, and outputs outside of your process. That would be things like database writes, remote procedure calls, printing to the console, etc.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">I don\u2019t know a common term for the hidden inputs, but I would call these dependencies on global state. Again, there are two flavors: dependency on the state of some global variable, or a dependency on the state of the system your program is running in. That\u2019s things like permissions to access the database, the existence of a given file on the file system, and even the ability to read the system clock.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_61-1024x576.png\" alt=\"\" class=\"wp-image-340\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_61-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_61-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_61-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_61.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">So why are these hidden inputs and outputs a problem? They make code hard to test, hard to reuse, and hard to reason about.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Hard to test because you have to make sure you have all the necessary dependencies are set up before you can even run the method in your test. And then once you do run the method, side effects often force the test to rely more on interaction verification than state verification, which can be brittle.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Hard to reuse because the code now makes assumptions about what kinds of resources you have available to you. If you need to reuse some method in another part of the codebase, but the input data needs to come from a different source, or you need to store the results in a different place, those side effects and global states are going to create a tight coupling between your computation code and the specific sources and destinations for that computation, which will make your life harder.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Hard to reason about because, by definition, these inputs and outputs are hidden! If you don\u2019t even know that your method is making these kinds of assumptions on the system that it\u2019s running in, then you\u2019re going to make some faulty conclusions about how your code will behave.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_62-1024x576.png\" alt=\"\" class=\"wp-image-341\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_62-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_62-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_62-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_62.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Now I\u2019m not saying all side effects or global state are bad. And I\u2019m not saying we should all immediately switch to a pure functional programming language like Haskell.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Effects have to happen somewhere. Without side effects, computation is just the process of making a metal box hot for a little while<br>(and even that heat is a side effect! although not usually one we care about).<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">But by default, we tend to sprinkle them everywhere throughout the code. Need some input? Just read the file at whatever point you happen to be at in the code. Need to store your result? Go ahead and do it 4 layers deep into your business logic.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Without a principled approach to side effects and global state, we\u2019re constantly running into the kinds of problems we just described.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_63-1024x576.png\" alt=\"\" class=\"wp-image-342\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_63-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_63-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_63-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_63.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">There\u2019s a better way, which is to isolate the side effects and the dependencies on global state. Much of our code is just logic on top of the data (once we get it) and creating new data based on that. Divide your code into the computational parts on one hand, and the parts that deal with side effects and global state on the other.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_64-1024x576.png\" alt=\"\" class=\"wp-image-343\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_64-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_64-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_64-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_64.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">There are a few common patterns for this.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">One of them is Command\/Query Separation. It\u2019s a pattern where each method is either a command, which performs some side effect, or a query, which is a pure function that returns its output as the return value. But you maintain a strict separation so that no function does both of those things.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Another pattern is called \u201cFunctional Core, Imperative Shell\u201d. This is a pattern at the architectural level. You focus the inner modules of your system on the business logic and computation, not performing side effects &#8211; this is the \u201cfunctional core\u201d. The outer modules coordinate the effects of your system with that computation, so that the complexity of the side effects is isolated to just that outer layer, and the majority of your system is simpler due to the functional purity.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_65-1024x576.png\" alt=\"\" class=\"wp-image-344\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_65-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_65-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_65-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_65.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">As with the other two practices, side effects and global state have a big impact on how we think about code.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">For example, you might be working on a method and need to delete a file. Your assumption is that it should be okay, you think no one is using it.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_66-1024x576.png\" alt=\"\" class=\"wp-image-345\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_66-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_66-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_66-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_66.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">But then it turns out, some other part of the codebase was relying on it, and you just broke them. The code was so far away and unrelated that you didn\u2019t even think to check there.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_67-1024x576.png\" alt=\"\" class=\"wp-image-346\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_67-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_67-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_67-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_67.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">On the other hand, if you isolate your side effects and global state such that they only happen in a known region of the code, then you can have confidence that you really aren\u2019t going to break anyone else.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_68-1024x576.png\" alt=\"\" class=\"wp-image-347\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_68-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_68-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_68-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_68.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">So, those are the three starter practices for Design for Understandability: Design by Contract, Data Invariants, and Isolating Side Effects and Dependencies on Global State.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_69-1024x576.png\" alt=\"\" class=\"wp-image-348\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_69-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_69-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_69-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_69.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Now, I\u2019ve presented these as independent practices, but in fact they\u2019re not so distinct. There\u2019s a unifying theme to them. That theme is local reasoning.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_70-1024x576.png\" alt=\"\" class=\"wp-image-349\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_70-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_70-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_70-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_70.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">What do I mean by local reasoning?<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Local reasoning means you can come to conclusions about some chunk of code by looking only at that chunk of code, plus just a small amount of the neighboring code, like the specifications or contracts of the components that you directly interact with.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_71-1024x576.png\" alt=\"\" class=\"wp-image-350\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_71-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_71-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_71-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_71.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">This is as opposed to global reasoning. That\u2019s the kind of reasoning where to answer even a simple question, you have to read a large chunk of the codebase, because the answer could be in any method, at any level of the call stack.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The benefit of local reasoning is that it puts a hard boundary on how far you have to look in order to figure something out about your system: there\u2019s always a limit to how far you have to search.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_72-1024x576.png\" alt=\"\" class=\"wp-image-351\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_72-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_72-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_72-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_72.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">So let\u2019s talk about how each of the practices we talked about enables local reasoning. You may have noticed we covered this already, but let\u2019s review.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_73-1024x576.png\" alt=\"\" class=\"wp-image-352\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_73-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_73-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_73-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_73.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Design by Contract defines the expected behavior for a caller and a called method. That means that to understand what behavior a caller can rely on, or what behavior a called method is obligated to implement, the only place we need to look is the defined interface for that called method. Without that, we would revert to global reasoning to find all the parts of the code that might depend on some aspect of this method\u2019s behavior.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_74-1024x576.png\" alt=\"\" class=\"wp-image-353\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_74-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_74-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_74-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_74.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Data invariants often go hand in hand with contracts, but they usually say something about an entire object rather than a single method on that object.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">If you have a piece of data and you want to know something about its validity, like \u201cdoes this fridge have any diet cokes?\u201d, an invariant is what lets you immediately conclude yes, without looking at the callers that produced that data.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_75-1024x576.png\" alt=\"\" class=\"wp-image-354\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_75-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_75-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_75-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_75.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Finally, by isolating side effects and global state, you minimize the number of places in your code where a change in one part of the code can cause a problem in a completely unrelated part. So it lets you say things like \u201cthis is the only part of the code that\u2019s allowed to touch this file, so I know for sure that it\u2019s safe to delete\u201d.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_76-1024x576.png\" alt=\"\" class=\"wp-image-355\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_76-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_76-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_76-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_76.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Another way of looking at local reasoning is to say that it minimizes the amount of context we need in order to reason about the system.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">With global reasoning, you might need to know about any arbitrary part of your codebase, because the part that breaks your assumptions could be anywhere. You need to have the whole system loaded into your head in order to understand it.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Local reasoning keeps the amount of stuff you need loaded into your head to a reasonable size.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_77-1024x576.png\" alt=\"\" class=\"wp-image-356\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_77-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_77-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_77-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_77.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">And guess what else benefits from small contexts: LLMs!<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">A key portion of making an LLM useful for your work is giving an LLM the right context to give good suggestions. But contexts costs tokens, and your tokens are limited. So LLMs give us another great motivation to use local reasoning and minimize our context.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">In other words, if you want your LLMs to be useful to you, then design your systems for understandability. Keep the necessary context small to make it easier for both you and your LLM to work with your code.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_78-1024x576.png\" alt=\"\" class=\"wp-image-357\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_78-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_78-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_78-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_78.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">At the beginning of this talk, I compared &#8220;Design for Understandability&#8221; to &#8220;Design for Testability&#8221;. I\u2019d like to revisit that for a moment.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Before designing for testability was the norm, the default testing approach was application-level testing. Our code wasn\u2019t set up for practices like dependency injection, so there was no way to run your code without setting up a huge set of dependencies as well. It wasn\u2019t until we started designing and building our systems with testability in mind that we were able to make unit testing practical.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">That\u2019s how it is with understandability and local reasoning, as well. If you don\u2019t design for it ahead of time, it\u2019s somewhere between hard and impossible to use local reasoning. But if you design for it along the way, you can make it work.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">If you\u2019ve never heard of unit testing, then application-level testing seems obvious, and straightforward. But it\u2019s not sufficient for modern software engineering. The same is true for global reasoning. I say it\u2019s time we made designing for understandability a required part of our work, just like we did for testability.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_79-1024x576.png\" alt=\"\" class=\"wp-image-358\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_79-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_79-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_79-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_79.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">So you may be thinking: that all sounds good, and these practices sound good on paper, but is designing for understandability feasible in practice? You\u2019re probably not working in a brand-new greenfield project. You\u2019re probably working on old code, with lots of old warts and complexity, and the situation may seem hopeless. Can you really do this?<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_80-1024x576.png\" alt=\"\" class=\"wp-image-359\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_80-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_80-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_80-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_80.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">I\u2019m here to say yes, this is feasible, if you take it one small step at a time. I\u2019ll share some tips for getting started.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_81-1024x576.png\" alt=\"\" class=\"wp-image-360\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_81-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_81-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_81-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_81.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">First off, take little bits at a time. Don&#8217;t try to boil the ocean. Don&#8217;t say &#8220;We&#8217;re going to take two weeks off from our normal work, make all of our code perfectly understandable, and then we&#8217;re done!&#8221;. That&#8217;s not going to work; you&#8217;re going to have a bad time.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Instead, try applying some of these practices to just new methods that you write. You might have some old code out there that&#8217;s hard to change. So be it. Start with just the new methods and build some momentum.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Teach your teammates, as well. Maybe share this talk, or find other ways to help your teammates design for understandability.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">And finally, you might consider group programming sessions where you all get together and discuss: what does designing for understandability mean in your context? The Monarch team at Google did this with their Design by Contract practice and it worked well for them.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_83-1024x576.png\" alt=\"\" class=\"wp-image-362\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_83-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_83-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_83-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_83.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Here are some further resources to learn more about Design for Understandability. I&#8217;m not going to go into them in detail, but please feel free to go revisit the slides after the talk and check these out.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">[Public links reproduced here for the blog post:]<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/ieeexplore.ieee.org\/document\/8611447\">Intellectual Control<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/www.cs.utexas.edu\/~EWD\/transcriptions\/EWD03xx\/EWD340.html\">The Humble Programmer<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/lexi-lambda.github.io\/blog\/2019\/11\/05\/parse-don-t-validate\/\">Parse, Don&#8217;t Validate<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/www.destroyallsoftware.com\/screencasts\/catalog\/functional-core-imperative-shell\">Functional Core, Imperative Shell<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/fsharpforfunandprofit.com\/composition\">The Power of Composition<\/a><\/li>\n<\/ul>\n\n\n\n<figure class=\"wp-block-image size-large presentation-slide\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"576\" src=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_84-1024x576.png\" alt=\"\" class=\"wp-image-363\" srcset=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_84-1024x576.png 1024w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_84-300x169.png 300w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_84-768x432.png 768w, https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_84.png 1080w\" sizes=\"auto, (max-width: 1024px) 100vw, 1024px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">In conclusion: design your code for understandability. Whenever you\u2019re working on some code and realize that you\u2019re falling back to global reasoning, pause for a moment. Ask yourself: can I do this with local reasoning instead? Would a contract or an invariant help here? Or what if I moved the side effects and global state somewhere else? Or, maybe you\u2019ll think of some other practice that fits here &#8211; you probably know a lot of local-reasoning practices, even if you didn\u2019t have the terminology to call it that until today.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">It\u2019s time to make design for understandability just as much a part of software engineering as designing for testability is today. Understandability is not just helpful &#8211; it\u2019s crucial, especially with Google-size systems. And not just that, but making your code understandable is doable if you design for it along the way.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Trust me: you\u2019ll be glad you did.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n","protected":false},"excerpt":{"rendered":"<p>This is a talk I gave at Google&#8217;s internal Code Health Summit in November of 2025. I&#8217;m sharing it here in the hopes that it sparks further learning and discussion. Abstract In a world where LLMs generate much of our code, understanding that code is more important than ever. But with a system as large &hellip; <a href=\"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/\" class=\"more-link\">Continue reading <span class=\"screen-reader-text\">Design for Understandability<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":"[]"},"categories":[1],"tags":[],"class_list":["post-276","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v28.9 - https:\/\/yoast.com\/product\/yoast-seo-wordpress\/ -->\n<title>Design for Understandability - Schuster on Software<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Design for Understandability\" \/>\n<meta property=\"og:description\" content=\"This is a talk I gave at Google&#8217;s internal Code Health Summit in November of 2025. I&#8217;m sharing it here in the hopes that it sparks further learning and discussion. Abstract In a world where LLMs generate much of our code, understanding that code is more important than ever. But with a system as large &hellip; Continue reading Design for Understandability\" \/>\n<meta property=\"og:url\" content=\"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/\" \/>\n<meta property=\"og:site_name\" content=\"Schuster on Software\" \/>\n<meta property=\"article:published_time\" content=\"2026-11-19T13:03:35+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2026-11-19T13:03:36+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_6.png\" \/>\n\t<meta property=\"og:image:width\" content=\"1080\" \/>\n\t<meta property=\"og:image:height\" content=\"607\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/png\" \/>\n<meta name=\"author\" content=\"Jonathan Schuster\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Jonathan Schuster\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"41 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/2026\\\/11\\\/19\\\/design-for-understandability\\\/#article\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/2026\\\/11\\\/19\\\/design-for-understandability\\\/\"},\"author\":{\"name\":\"Jonathan Schuster\",\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/#\\\/schema\\\/person\\\/3162b1cd747cb086d2ea57b4b59cbbf4\"},\"headline\":\"Design for Understandability\",\"datePublished\":\"2026-11-19T13:03:35+00:00\",\"dateModified\":\"2026-11-19T13:03:36+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/2026\\\/11\\\/19\\\/design-for-understandability\\\/\"},\"wordCount\":5700,\"commentCount\":0,\"publisher\":{\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/#\\\/schema\\\/person\\\/3162b1cd747cb086d2ea57b4b59cbbf4\"},\"image\":{\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/2026\\\/11\\\/19\\\/design-for-understandability\\\/#primaryimage\"},\"thumbnailUrl\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/10\\\/page_1-1024x576.png\",\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\\\/\\\/jschuster.org\\\/blog\\\/2026\\\/11\\\/19\\\/design-for-understandability\\\/#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/2026\\\/11\\\/19\\\/design-for-understandability\\\/\",\"url\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/2026\\\/11\\\/19\\\/design-for-understandability\\\/\",\"name\":\"Design for Understandability - Schuster on Software\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/2026\\\/11\\\/19\\\/design-for-understandability\\\/#primaryimage\"},\"image\":{\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/2026\\\/11\\\/19\\\/design-for-understandability\\\/#primaryimage\"},\"thumbnailUrl\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/10\\\/page_1-1024x576.png\",\"datePublished\":\"2026-11-19T13:03:35+00:00\",\"dateModified\":\"2026-11-19T13:03:36+00:00\",\"breadcrumb\":{\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/2026\\\/11\\\/19\\\/design-for-understandability\\\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/jschuster.org\\\/blog\\\/2026\\\/11\\\/19\\\/design-for-understandability\\\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/2026\\\/11\\\/19\\\/design-for-understandability\\\/#primaryimage\",\"url\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/10\\\/page_1.png\",\"contentUrl\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/10\\\/page_1.png\",\"width\":1080,\"height\":607},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/2026\\\/11\\\/19\\\/design-for-understandability\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Design for Understandability\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/#website\",\"url\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/\",\"name\":\"Schuster on Software\",\"description\":\"\",\"publisher\":{\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/#\\\/schema\\\/person\\\/3162b1cd747cb086d2ea57b4b59cbbf4\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"},{\"@type\":[\"Person\",\"Organization\"],\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/#\\\/schema\\\/person\\\/3162b1cd747cb086d2ea57b4b59cbbf4\",\"name\":\"Jonathan Schuster\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/11\\\/me.jpg\",\"url\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/11\\\/me.jpg\",\"contentUrl\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/11\\\/me.jpg\",\"width\":200,\"height\":200,\"caption\":\"Jonathan Schuster\"},\"logo\":{\"@id\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/11\\\/me.jpg\"},\"sameAs\":[\"https:\\\/\\\/jschuster.org\\\/\",\"https:\\\/\\\/www.linkedin.com\\\/in\\\/jonathanpschuster\\\/\"],\"url\":\"https:\\\/\\\/jschuster.org\\\/blog\\\/author\\\/jschuster\\\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Design for Understandability - Schuster on Software","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/","og_locale":"en_US","og_type":"article","og_title":"Design for Understandability","og_description":"This is a talk I gave at Google&#8217;s internal Code Health Summit in November of 2025. I&#8217;m sharing it here in the hopes that it sparks further learning and discussion. Abstract In a world where LLMs generate much of our code, understanding that code is more important than ever. But with a system as large &hellip; Continue reading Design for Understandability","og_url":"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/","og_site_name":"Schuster on Software","article_published_time":"2026-11-19T13:03:35+00:00","article_modified_time":"2026-11-19T13:03:36+00:00","og_image":[{"width":1080,"height":607,"url":"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_6.png","type":"image\/png"}],"author":"Jonathan Schuster","twitter_card":"summary_large_image","twitter_misc":{"Written by":"Jonathan Schuster","Est. reading time":"41 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/#article","isPartOf":{"@id":"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/"},"author":{"name":"Jonathan Schuster","@id":"https:\/\/jschuster.org\/blog\/#\/schema\/person\/3162b1cd747cb086d2ea57b4b59cbbf4"},"headline":"Design for Understandability","datePublished":"2026-11-19T13:03:35+00:00","dateModified":"2026-11-19T13:03:36+00:00","mainEntityOfPage":{"@id":"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/"},"wordCount":5700,"commentCount":0,"publisher":{"@id":"https:\/\/jschuster.org\/blog\/#\/schema\/person\/3162b1cd747cb086d2ea57b4b59cbbf4"},"image":{"@id":"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/#primaryimage"},"thumbnailUrl":"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_1-1024x576.png","inLanguage":"en-US","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/#respond"]}]},{"@type":"WebPage","@id":"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/","url":"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/","name":"Design for Understandability - Schuster on Software","isPartOf":{"@id":"https:\/\/jschuster.org\/blog\/#website"},"primaryImageOfPage":{"@id":"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/#primaryimage"},"image":{"@id":"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/#primaryimage"},"thumbnailUrl":"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_1-1024x576.png","datePublished":"2026-11-19T13:03:35+00:00","dateModified":"2026-11-19T13:03:36+00:00","breadcrumb":{"@id":"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/#primaryimage","url":"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_1.png","contentUrl":"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/10\/page_1.png","width":1080,"height":607},{"@type":"BreadcrumbList","@id":"https:\/\/jschuster.org\/blog\/2026\/11\/19\/design-for-understandability\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/jschuster.org\/blog\/"},{"@type":"ListItem","position":2,"name":"Design for Understandability"}]},{"@type":"WebSite","@id":"https:\/\/jschuster.org\/blog\/#website","url":"https:\/\/jschuster.org\/blog\/","name":"Schuster on Software","description":"","publisher":{"@id":"https:\/\/jschuster.org\/blog\/#\/schema\/person\/3162b1cd747cb086d2ea57b4b59cbbf4"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/jschuster.org\/blog\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":["Person","Organization"],"@id":"https:\/\/jschuster.org\/blog\/#\/schema\/person\/3162b1cd747cb086d2ea57b4b59cbbf4","name":"Jonathan Schuster","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/11\/me.jpg","url":"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/11\/me.jpg","contentUrl":"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/11\/me.jpg","width":200,"height":200,"caption":"Jonathan Schuster"},"logo":{"@id":"https:\/\/jschuster.org\/blog\/wp-content\/uploads\/2026\/11\/me.jpg"},"sameAs":["https:\/\/jschuster.org\/","https:\/\/www.linkedin.com\/in\/jonathanpschuster\/"],"url":"https:\/\/jschuster.org\/blog\/author\/jschuster\/"}]}},"_links":{"self":[{"href":"https:\/\/jschuster.org\/blog\/wp-json\/wp\/v2\/posts\/276","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/jschuster.org\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/jschuster.org\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/jschuster.org\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/jschuster.org\/blog\/wp-json\/wp\/v2\/comments?post=276"}],"version-history":[{"count":21,"href":"https:\/\/jschuster.org\/blog\/wp-json\/wp\/v2\/posts\/276\/revisions"}],"predecessor-version":[{"id":406,"href":"https:\/\/jschuster.org\/blog\/wp-json\/wp\/v2\/posts\/276\/revisions\/406"}],"wp:attachment":[{"href":"https:\/\/jschuster.org\/blog\/wp-json\/wp\/v2\/media?parent=276"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/jschuster.org\/blog\/wp-json\/wp\/v2\/categories?post=276"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/jschuster.org\/blog\/wp-json\/wp\/v2\/tags?post=276"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}