<h2>The state of the site</h2>
<p>This site is now made with <a href="https://nextjs.org/">Next.js</a> and hosted on Netlify.</p>
<p>For over a year I used my <a href="notes-on-writing-a-static-site-generator.html">own hand-crafted SSG</a>. It was really nice. But:</p>
<ol>
<li>I wanted to learn Next.js.</li>
<li>I love how fast the navigation is.</li>
<li>I still <a href="on-dependencies-in-small-projects.html">don't need many dependencies</a>, and I'm finding Next to be very well-behaved and stable.</li>
<li>A lot of the site infrastructure is the same (I just copied it over).</li>
</ol>
<p>So, this site isn't quite as hand-crafted as it used to be (or, at least, not quite as hand-crafted <em>by me</em>)--but you ought to be able to click around a lot more easily. And I still think that taking on dependencies <a href="on-dependencies-in-small-projects.html">is overrated</a>.</p>

The state of the site

<head><link rel='stylesheet' href='https://fonts.googleapis.com/css?family=Mukta'>
        <style>
        body {
            background-color: #D8D8D8;
            margin-top: 50px;
            font-family: "Mukta";
            font-size: large;
            max-width: 650px;
            margin-left: auto;
            margin-right: auto;
        }
        footer {
            max-width: 650px;
            margin-left: auto;
            margin-right: auto;
        }
        li {
            margin-top: 5px;
        }
        .markdown-output {
            max-width: 650px;
            margin-left: auto;
            margin-right: auto;
        }
        </style>
    <meta name='description' content='How not to learn software'>
<title>How not to learn software</title>
</head>
<div>

<div class='markdown-output'><h2>How not to learn software</h2>
<p>I stand by <a href="on-learning-vim.html">this post</a> on learning Vim. 
Now I want to double down on the third point I made there: 
If you're new to Vim, default to <em>not</em> installing plugins. 
And only make a <code>.vimrc</code> when you really need to. 
Here's why:</p>
<ol>
<li>What the plugin does is often doable in vanilla Vim.</li>
<li>If it's not, there's probably a reason vanilla Vim doesn't include it.</li>
<li>The time you spend worrying about the plugin is time you can't spend learning Vim itself.</li>
<li>Plugins are buggy.</li>
<li>Plugins can be hard to install and maintain.</li>
<li>To the extent you rely on plugins, your Vim skills are less portable. When you fire up Vim on whatever server you need to be working in, some of your muscle memory won't apply.</li>
</ol>
<p>Eventually, you'll need to install a plugin (e.g., for Copilot) or persist a preference (e.g., about indentation). 
But your .vimrc and plugins are like any other code in that you'll pay a maintenance cost as long as you have them.</p></div>

</div>




<hr>
<a href='index.html'>Home page</a>


How not to learn software

<head><link rel='stylesheet' href='https://fonts.googleapis.com/css?family=Mukta'>
        <style>
        body {
            background-color: #D8D8D8;
            margin-top: 50px;
            font-family: "Mukta";
            font-size: large;
            max-width: 650px;
            margin-left: auto;
            margin-right: auto;
        }
        footer {
            max-width: 650px;
            margin-left: auto;
            margin-right: auto;
        }
        li {
            margin-top: 5px;
        }
        .markdown-output {
            max-width: 650px;
            margin-left: auto;
            margin-right: auto;
        }
        </style>
    <meta name='description' content='Testing decorated functions in Python web frameworks'>
<title>Testing decorated functions in Python web frameworks</title>
</head>
<div>

<div class='markdown-output'><h2>Testing decorated functions in Python web frameworks</h2>
<p>The meaty parts of Web frameworks, the parts that determine what happens when you hit a certain URL, often have a similar structure.
Here's an example from Bottle, a Python framework:</p>
<h5><code>hats.py</code></h5>
<pre><code>@app.route('/hats')
def get_hat_names():
    hat_names = db.connection.execute(&quot;SELECT name FROM hats&quot;).fetchall()
    return hat_template(hat_names = hat_names)
</code></pre>
<p>Very similar patterns exist in Django and Flask. 
(Also in non-Python frameworks, but for concreteness I'll use only Python examples.)</p>
<p>Now: how do you <em>test</em> <code>get_hat_names</code>?</p>
<p>The answer starts with the observation that things are not, in practice, as simple as the example above. 
Let's make the example slightly more realistic:</p>
<h5><code>hats.py</code></h5>
<pre><code># You have some imports

# Somewhere you have a Django Router, a Flask object, or a Bottle command.

@app.route('/hats')
def show_hats(style: str = Form(...)): # In Django and other frameworks, there would be a `request` parameter here
    style_enum_value = Style[style].value # Style is an enum you're importing
    hat_names = db.connection.execute(&quot;SELECT name FROM hats WHERE style = {style_enum_value}&quot;).fetchall()
    sale_hat_names = db.connection.execute(&quot;SELECT hat_name FROM sales WHERE status = 'active'&quot;).fetchall()
    if not hat_names:
        return no_hats_template()
    sale_items = [hat_name for hat_name in hat_names if hat_name in sale_hat_names]
    return hat_template(hat_names = hat_names, sale_items = sale_items)
</code></pre>
<p>There are at least four problems that arise in testing a function like this:</p>
<ol>
<li>The function is more complicated than you'd want it to be for testing.</li>
<li>The function uses (closes over, if you prefer) items from the surrounding context These items often include routers, environment variables, and database connections.</li>
<li>You tend to need mocks: e.g., of database connections and of Django <code>Request</code> objects.</li>
<li>The function is decorated, and there's a lot of behavior happening in the wrapped function (but not the first-order <code>show_hats</code> function) that will interfere with your attempts to interact with it in tests.</li>
</ol>
<p>(Those problems are interrelated, but also multifaceted. 
You might say those are actually two problems or actually six. 
Never mind.)</p>
<p>Here's how I test these functions without creating an opaque wad of mocks and set-up functions.</p>
<h4>Step one: put persistence-related information behind an interface</h4>
<p>Create an interface that abstracts away the details of a particular database configuration:</p>
<h5><code>hat_repository.py</code></h5>
<pre><code>class HatRepository:
    @abstractmethod
    def get_hat_names(self, style_enum_value):
        raise NotImplementedError

    @abstractmethod
    def get_sale_hat_names(self, style_enum_value):
        raise NotImplementedError

class SQLHatRepository(HatRepository):
    def __init__(self, db_path):
        # Do your database setup
        pass

    def get_hat_names(self, style_enum_value):
        return db.connection.execute(&quot;SELECT name FROM hats WHERE style = {style_enum_value}&quot;).fetchall()

    def get_sale_hat_names(self, style_enum_value):
        return db.connection.execute(&quot;SELECT hat_name FROM sales WHERE status = 'active' AND style = {style_enum_value}&quot;).fetchall()
</code></pre>
<p>This will help us a lot here. 
It will help us a lot <em>everywhere</em>, in fact: it's a powerful abstraction. 
(<em>Architecture Patterns with Python</em> is the best treatment I've read of the so-called "repository pattern.")</p>
<p>Then rewrite your decorated framework functions to depend not on a raw database connection but on an instance of the repository:</p>
<h5><code>hats.py</code></h5>
<pre><code># You have some imports

# Somewhere you have a Django Router, a Flask object, or a Bottle command

repo = SQLHatRepository(&quot;db_path.db&quot;)

@app.route('/hats')
def show_hats(style: str = Form(...)): # In Django and other frameworks, there would be a `request` parameter here
    style_enum_value = Style[style].value
    hat_names = repo.get_hat_names(style_enum_value)
    sale_hat_names = repo.get_sale_hat_names(style_enum_value)
    if not hat_names:
        return no_hats_template()
    sale_items = [hat_name for hat_name in hat_names if hat_name in sale_hat_names]
    return hat_template(hat_names = hat_names, sale_items = sale_items)
</code></pre>
<h4>Step two: put all substantial logic in a helper function</h4>
<p>In our example, this would work like this:</p>
<h5><code>hat_helpers.py</code></h5>
<pre><code>def _show_hats(repo, style_enum_value):
    hat_names = repo.get_hat_names(style_enum_value)
    sale_hat_names = repo.get_sale_hat_names(style_enum_value)
    sale_items = [hat_name for hat_name in hat_names if hat_name in sale_hat_names]
    return (hat_names, sale_items)
</code></pre>
<h5><code>hats.py</code></h5>
<pre><code># You have some imports

# Somewhere you have a Django Router, a Flask object, or a Bottle command

from hat_helpers import _show_hats

repo = SQLHatRepository(&quot;db_path.db&quot;)

@app.route('/hats')
def show_hats(style: str = Form(...)): # In Django and other frameworks, there would be a `request` parameter here
    style_enum_value = Style[style].value
    hat_names, sale_items = _show_hats(repo, style_enum_value)
    if not hat_names:
        return no_hats_template()
    return hat_template(hat_names = hat_names, sale_items = sale_items)
</code></pre>
<p>The division of work above is common:</p>
<ol>
<li>The main decorated function parses inputs, which are often require transformation from what is passed in to the function. Most commonly, this is a matter of parsing strings or extracting fields from a request.</li>
<li>The main decorated function feeds values into templates.</li>
<li>The helper function does everything else.</li>
</ol>
<h4>Step three: test the helper function</h4>
<p>Now you have a helper function, <code>_show_hats</code>, that is perfectly testable:</p>
<ol>
<li>You can create a test-friendly subclass of <code>HatRepository</code>.</li>
<li>No mocks are required.</li>
<li>If the logic is complicated, you can (and should!) split it out and test those smaller functions separately.</li>
<li>You can import the helper without invoking side effects from your Web framework's router initialization, database connection, or anything else.</li>
</ol>
<h4>This looks like an anti-pattern, but it isn't</h4>
<p>You might resist this solution: aren't these just "pass-through functions" of the sort John Osterhout <a href="reading-notes-a-philosophy-of-software-design.html">warns us about</a>? 
To have a function doing little more than passing arguments through is a well-known anti-pattern. 
What I'm recommending here, however, only <em>look</em> like pass-through functions. 
There's a lot of action happening in the decorator. 
To avoid pulling as much as possible out of these functions is to be deceived by syntax.</p></div>

</div>




<hr>
<a href='index.html'>Home page</a>


Testing decorated functions in Python web frameworks

<head><link rel='stylesheet' href='https://fonts.googleapis.com/css?family=Mukta'>
        <style>
        body {
            background-color: #D8D8D8;
            margin-top: 50px;
            font-family: "Mukta";
            font-size: large;
            max-width: 650px;
            margin-left: auto;
            margin-right: auto;
        }
        footer {
            max-width: 650px;
            margin-left: auto;
            margin-right: auto;
        }
        li {
            margin-top: 5px;
        }
        .markdown-output {
            max-width: 650px;
            margin-left: auto;
            margin-right: auto;
        }
        </style>
    <meta name='description' content='Notes on coding with ChatGPT'>
<title>Notes on coding with ChatGPT</title>
</head>
<div>

<div class='markdown-output'><h2>Notes on coding with ChatGPT</h2>
<ol>
<li>This is real.</li>
<li>There's a sort of endurance that coding with ChatGPT uniquely requires. You have to maintain the discipline to keep asking ChatGPT where appropriate; it's tempting to plow through a problem unassisted, especially when you've just asked ChatGPT for help a half-dozen times. You have to remember that ChatGPT is not getting tired or annoyed, and that you're not keeping ChatGPT from working on something more important. There's a certain social instinct that must be slightly repressed: entering into conversation of any sort prompts us to spin up various emotional capacities. Some of these are in fact good to maintain even when the interlocutor is ChatGPT, but many stop being worth the energy when it's not a human being on the other side.</li>
<li>The skill of dealing with code you didn't write, which has always been an important part of software engineering, is perhaps now even <em>more</em> important, given that you won't even have written a bunch of the code that you wrote.</li>
<li>There's a particular skill of remembering to double-check sources that are right perhaps 95% of the time. As I get better with ChatGPT, it has been harder to catch its mistakes, because its accuracy rate is sometimes so high that it comes to seem extremely convincing. (At Google there was an absolutely magical development tool that hot-swapped fixes into a development environment as you coded. It worked perhaps 99% of the time. I tended to lose hours chasing my tail when a 1% case hit.)</li>
<li>If you are coding with Copilot, don't be afraid to type "This is confusing because" and wait for the autocomplete.</li>
</ol></div>

</div>




<hr>
<a href='index.html'>Home page</a>


Notes on coding with ChatGPT

<head><link rel='stylesheet' href='https://fonts.googleapis.com/css?family=Mukta'>
        <style>
        body {
            background-color: #D8D8D8;
            margin-top: 50px;
            font-family: "Mukta";
            font-size: large;
            max-width: 650px;
            margin-left: auto;
            margin-right: auto;
        }
        footer {
            max-width: 650px;
            margin-left: auto;
            margin-right: auto;
        }
        li {
            margin-top: 5px;
        }
        .markdown-output {
            max-width: 650px;
            margin-left: auto;
            margin-right: auto;
        }
        </style>
    <meta name='description' content='A note on 10x engineering'>
<title>A note on 10x engineering</title>
</head>
<div>

<div class='markdown-output'><h2>A note on 10x engineering</h2>
<p>Taylor <a href="https://taylor.town/-10x">argues that</a>, whereas "10x engineers may be mythical, -10x engineers exist." The form of argument is: it's pretty easy to waste ten engineers' worth of time and effort. He gives a long list of ways to do this.</p>
<p>It's a good argument, and it shows more than Taylor makes explicit. If he's right that there are so many dimensions of impact along which engineers can be much better and worse than each other, then I think you have to believe one of two things:</p>
<ol>
<li>Most or all of these dimensions have unbounded downside but fairly low ceilings, or</li>
<li>The best engineers really <em>are</em> vastly better than average ones, because they can be better along many high-impact axes--or at least a few.</li>
</ol>
<p>Moreover, Taylor barely discusses system design and architecture, and then only to discuss the costs of truly bad and sloppy planning. I'd also emphasize that the difference between mediocre and good system design is very large.</p>
<p>So: I don't know how sincere Taylor was when he said that 10x engineers are mythical, but it's very hard both to accept his argument for the existence of -10x engineers and to deny that 10x engineers exist.</p></div>

</div>




<hr>
<a href='index.html'>Home page</a>


A note on 10x engineering

<h4>On trees and dimensionality</h4>
<p>Here's <a href="https://www.robertbeard.info/2022/03/21/subtree-matching.html">a crisp and thorough essay</a> from Robert Beard thinking through the problem of finding exact matches for a subtree in a larger tree. Unsurprisingly, you can help yourself by preprocessing the larger tree.</p>
<p>(I say "unsurprising" because there are so many graph algorithms that (i) are linear in the size of the graph, so not asymptotically more costly than simply reading the graph; (ii) straightforward to implement; and (iii) extremely informative. Tim Roughgarden calls these "<a href="https://theory.stanford.edu/~tim/won1samplefinal.pdf">for-free primitives</a>," which is a great way to think about them.)</p>
<p>The striking part (to me) of Robert's discussion is the value of preprocessing the large tree by labeling each node with its height (distance from the nearest leaf). Once you do that, you know that any node with height smaller than the height of the smaller tree cannot be the root of a match. So you can lop off the bottom of the tree from consideration.</p>
<p>Even if you're not worried about graph algorithms or interview questions, it's worth keeping in mind that most of a tree is near the bottom (if the tree is balanced or nearly so):</p>
<ol>
<li>It's the key to seeing why <a href="https://stackoverflow.com/questions/9755721/how-can-building-a-heap-be-on-time-complexity">a heap can be constructed in linear time</a>;</li>
<li>It's why one or the other of breadth-first and depth-first search can be much better than the other, even though both take linear time (sometimes solutions are more likely to be found nearer to the start);</li>
<li>It's why searching a game tree just a little bit farther can take a whole lot longer;</li>
<li>And I'm pretty sure it helps explain why <a href="https://en.wikipedia.org/wiki/A*_search_algorithm">A* search</a> is so powerful in practice.</li>
</ol>
<p>And from here it's a short step to more general facts about plane and solid geometry, which I use, on average, more than once a day in the kitchen:</p>
<ol>
<li>If carrots <em>A</em> and <em>B</em> are the same shape, but <em>A</em> is twice as long as <em>B</em>, it will yield eight times as much food (as long as you peel carefully);</li>
<li>The cooking time of a meatball or roasted vegetable is extremely sensitive to how big the items are (so don't have much faith in listed cooking times, and if err on the side of making them small if you're in a hurry);</li>
<li>It's a big mistake to assume that every apple in the fridge is calorically equivalent.</li>
</ol>
<p>See also the <a href="https://en.wikipedia.org/wiki/Curse_of_dimensionality">curse of dimensionality</a>. This all reminds me of how the Euclidean algorithm is often classified as "elementary," but roughly once a year I come to believe I've never properly understood it before.</p>

On trees and dimensionality

<h2>Code correctly by conforming to the real world</h2>
<p>I <a href="why-events.html">recently wrote about</a> why it makes sense to use events in many programming situations. There's more to say about the example and why events are correct there: the lesson applies more generally and will help you make good decisions about more than just event modeling.</p>
<p>We are modeling a soccer game and we have:</p>
<ol>
<li>The basic apparatus of the game: the field, the ball, players, and teams.</li>
<li>An assistant referee, which in the primitive state of this hypothetical application is just a mechanism for determining whether the ball is out of bounds or not.</li>
<li>The notion of a throw-in when a ball is out of bounds.</li>
</ol>
<p>There are, broadly, a few ways to handle the mechanics of awarding a throw-in:</p>
<ol>
<li>The assistant referee, upon determining that the ball is out of bounds, examines the recent state of the game (which team touched the ball last) and instigates the throw-in (to the other team) directly.</li>
<li>Teams (or players) will attempt to take the throw-in, and the assistant referee will permit or deny this.</li>
<li>The assistant referee will perform an event. This event will be processed by some central entity (you can think of this as a <code>Referee</code> object or a more general message bus.</li>
</ol>
<p>This sort of decision comes up all the time. And they're some of the most important decisions you make in programming. Important, common decisions are the best ones to study!</p>
<p>In that post I argued for the last option. Here are two further notes about making this kind of decision:</p>
<h4>Study dependency problems as dependency problems</h4>
<p>First, notice that this is <em>a dependency problem</em>. It can look like, and is often treated as, a purely mechanical problem about imports or an ergonomic problem about the convenience of methods you'll be implementing. There <em>are</em> import mechanics and ergonomics here, but those are manifestations of the fact that dependencies are being created. Worrying about dependencies <em>as dependencies</em> helps you resolve these other issues; trying to think about the issues independently of the fact that dependencies are involved leads to confusion.</p>
<p>What are some good heuristics for determining dependency directions?</p>
<ol>
<li>Think about operations you need to do now, and choose the direction that will accommodate them most easily.</li>
<li>Try to anticipate possible <em>future</em> operations, and choose the direction that will be accommodate those changes most easily.</li>
<li>Try to anticipate possible future <em>modifications</em>, and choose the direction that will facilitate those.</li>
</ol>
<p>Here, by the way, are some <em>bad</em> but commonly used heuristics for making this choice:</p>
<ol>
<li>Think about the order data will flow through the system, and make the later objects depend on the earlier ones. (John Ousterhout <a href="reading-notes-a-philosophy-of-software-design.html">diagnoses "temporal bias" errors very well</a>.)</li>
<li>Think about your preferred database and choose the one that most intuitively fits it.</li>
</ol>
<p>Here, the first two options are poor because they introduce inappropriate dependencies. The <code>AssistantReferee</code> object should not be rifling through game history, communicating with players, and doing whatever else would need doing if it were doing more than simply raising events. Nor should several players (or teams, or scorekeepers) have to issue separate requests to an assistant referee in order to determine what is happening. It might not sound as bad at first, but remember that not only the assistant referee but also the head referee, the head coach, and even the scoreboard or weather (is the game over? has thunder struck?) might change the result.</p>
<p>I find I make better decisions when I take the "because" in the previous paragraph very literally: bad decisions here are bad <em>because</em> they get the dependencies wrong. When you find yourself doing <a href="on-quadratic-complexity.html">unnecessary quadratic work</a>, debugging circular dependencies, or duplicating information because the alternative is too cumbersome, inappropriate dependencies are usually involved. Consider the case of quadratic work: this often happens because something is querying something else, and there are O(n) of each of those things. That, in turn, is often caused by information being stored with the latter thing instead of with the former thing. And that, in turn, is usually caused by a bad dependency.</p>
<p>Another hypothetical example in the spirit of something I've seen dozens of times: a library application is slow because every search requires a linear scan over all books, which in turn is because books are storing information about which users can check them out when. If the information were stored with the user or with some sort of neutral arbiter, this wouldn't be necessary.</p>
<p>The second note about the soccer-events example is more controversial:</p>
<h4>Worry more about what the things you're modeling <em>really are</em></h4>
<p>The previous argument attempted to establish that many problems are not only correlated with but <em>caused by</em> dependency problems. These issues become clearer when you also recognize that dependency problems (and other problems) are caused by a bad match between your code and reality. That is, your bad dependency is a bad dependency because it fails to conform to the world. In the soccer example, when we introduce events, we conform more closely to reality: the job of the head referee <em>really is</em> to be, among other things, an event broker. </p>
<p>What about the heuristics from before? Going in turn:</p>
<ol>
<li>The operations you need to do now are very likely to be operations that have some real-world analogue. The more faithfully you model reality, the more elegantly you'll be able to implement those operations.</li>
<li>Same with the operations you don't need to support now but do need to support later.</li>
<li>And when things need to change more fundamentally in your code, it's often because something changed in the real world. The way things change in the real world are governed by their relationships in the real world. So, for example, if <em>X</em> persists even though some related <em>Y</em> changes, that's a good sign that <em>X</em> was more fundamental than <em>Y</em> and should have been modeled that way. Another common headache here is needing to do a large migration to, e.g., change a value from being treated as boolean to being treated as a member of a more robust enumeration. Almost always, the thing in the world that the value is representing never really had boolean structure. Rather, for contingent reasons there was no need to express more than two states for that value, and a bad assumption that only two states were <em>possible</em> was baked into the interface.</li>
</ol>
<p>Each of those heuristics works because it keeps us in touch with reality. And this is where I find myself in deep agreement with the <a href="https://en.wikipedia.org/wiki/Domain-driven_design">domain-driven design</a> folks. I find the famous books in the tradition very difficult to read (except for <em>Architecture Patterns with Python</em>, which was a pleasure), and there tends to be a bit too much jargon and indoctrination there. But the core of DDD, as I understand it, is that you have to know which real-world domains you're working with, separate them cleanly, and model them correctly. This insight is valuable enough that it's worth wading through a lot of finger-wagging about <a href="https://en.wikipedia.org/wiki/Command–query_separation#Command_Query_Responsibility_Separation">CQRS</a>.</p>
<p>That is, each of those three heuristics (and pretty much any other reasonable heuristic you can think of) is a manifestation of a more fundamental principle. Your code will ultimately be accountable to the real world in some way, and that its success and failure will depend largely on how faithfully it models the world and how nimbly it adapts to changes in it.</p>

Code correctly by conforming to the real world

<h2>Code review reference</h2>
<p>If you are reading this because I've linked you here: the relevant section contains a canonical version of some shorter code review comment, and I'd be grateful if you reviewed it. Otherwise: hello and welcome to a list of things I commonly say in code reviews. (Hat tip to Eric Breck, who maintains a magnificent document in this form.)</p>
<h4>"Your near-synonymous variable names suggest that something is wrong."</h4>
<p>If, in the same function / file / class / whatever, you have <code>size</code> and <code>object_size</code>, <code>error</code> and <code>mistake</code>, <code>dimension</code> and <code>dim</code>, or similar, one of these problems is probably happening:</p>
<ol>
<li>Those two variables should be one. (Perhaps this is quick prototype code that hasn't been cleaned up yet.) The best fix is probably to collapse the two variables into one and adjust as appropriate.</li>
<li>One of those variables is misnamed.  Often, this seems to result from an unwillingness to admit that something needs to be represented at all. Perhaps you think you should have cleaned up the raw input corresponding to <em>X</em> by now but for whatever reason can't, but you don't want to say <code>raw_input_for_X</code>. The best fix--honesty being the best policy in code as elsewhere--is to rename the variables to describe accurately what they represent. You might also need to file a ticket describing the work that would need to be done to make the embarrassing thing unnecessary. (It's OK!)</li>
<li>Those variables represent the same underlying thing in different contexts. (Perhaps this is a system that's grown larger than planned.) The best short-term fix is, again, to be more accurate about what the variables represent, even if it's embarrassing.  In the longer term, planning in terms of <a href="https://martinfowler.com/bliki/BoundedContext.html">bounded contexts</a> might help.</li>
</ol>
<h4>"You're using a custom type or object here and keeping the definition in your head."</h4>
<p>Lists, tuples, and arrays make it easy to pass around related bits of information. 
Be careful not to rely on the sequential structure of these objects in a way that is semantically opaque. 
This is a common source of unnecessary coupling between components and of structure living in a programmer's head that should be living in code.</p>
<p>So, if you need to pass around an event's time and place, representing this information as [<code>foo_time</code>, <code>foo_place</code>] and making every user retrieve the time with <code>foo_information[0]</code> and the place with <code>foo_information[1]</code> creates an unnecessary burden. 
Make an <code>EventCircumstances</code> or <code>EventStamp</code> object (using a struct, a Python dataclass, a Java @AutoValue class, or any other appropriate mechanism). If you really want to represent that data with a list, feel free to do so under the hood, so long as distant callers don't need to know that "<code>[0]</code>" is how you say "<code>.place</code>" in this context.</p>
<h4>"This name is not semantically correct."</h4>
<p>Prefer to name things according to what they <code>are</code>, rather than the circumstances of their use. If you have an object representing a pizza, and you order pizza only on Tuesdays, name it <code>pizza</code>, not <code>food_we_order_on_tuesday</code>. Some common manifestations of this error are:</p>
<ol>
<li>Text fields. If the field is the serial number but is used by the header of the login screen, call it <code>serial_number</code>, not <code>login_screen_header_text</code>.</li>
<li>Exceptions. Exceptions are tricky, because you tend to want context (in a way that makes contextual information part of what the thing is), but still: If the exception arises from a failed widget validation, and that validation happens in your Jenkins CI, call it a <code>WidgetValidationException</code>, not a <code>JenkinsWidgetCheckException</code>.</li>
</ol>
<h4>"This layer of indirection is not permitting any useful abstraction."</h4>
<p>Let's say you're representing a light bulb's brightness. Right now you're representing it as a single number of lumens. If you decide to represent that as a <code>Brightness</code> with a single field: sure, let's abstract away from a single primitive data type, for all the usual reasons, including extensibility.</p>
<p>Now let's say you have a <code>Lightbulb</code> object that has <code>LightbulbProperties</code> (the only one of which is the <code>Brightness</code>). Here I'd worry not only that <code>Lightbulb</code> and <code>LightbulbProperties</code> are too nearly synonymous (see above) but that the extra wrapper around this single number of lumens isn't helping.</p>
<p>And if the <code>Lightbulb</code> has <code>LightbulbProperties</code> that has a <code>LightbulbBrightnessProperties</code> that has a <code>Brightness</code>,  you almost certainly have more indirection than actual abstraction. Remove at least one of these layers.</p>
<p>This issue commonly arises with central objects in a system, which programmers often feel (justifiedly) hesitant to create and modify directly. Jumping through the layers' definitions in an IDE can feel like watching someone put on latex glove after latex glove after latex glove in the hopes of not leaving a smudge on the vase they're about to handle. I respect the caution but would rather you be able to use your hands.</p>
<h4>"I don't think this thing you're trying to formalize can be formalized."</h4>
<p>See <a href="an-argument-from-jimmy-koppel.html">here</a>.</p>

Code review reference

<h2>Listening notes: Test and Code 191</h2>
<p>Eerily, <a href="https://testandcode.com/191">Test and Code 191</a> echoes some of <a href="notes-on-writing-a-static-site-generator.html">my thoughts on writing a static site generator</a>. 
It's entirely possible that they were recording the show as I was writing the post.</p>
<p>Test and Code is a real gem of the software podcast world. 
It's all steak and no sizzle. 
And I can prove <a href="my-information-diet.html">I thought so</a> even before I got the odd dose of flattery that is hearing one's slightly controversial beliefs affirmed on a respectable platform.
Episode 191 covered, among other things, the intersection of static site generation and testing.</p>
<p>My thoughts about writing the SSG powering this site grew out of <a href="15-notes-on-testing-software.html">my revised thoughts about testing</a>. 
I used to have an idealized view of testing: software breaks into atomic components; you should test all the atoms thoroughly; you should also test various relations among those atoms. 
I'm more pragmatic now. 
As I find things I need to be true of my code, I write tests for it. 
And when something breaks in my code, I write a test to check for that failure.
The latter I think of as "lazy testing," not in the psychological sense of "lazy" but as in "lazy evaluation," "lazy deletion," and the like. 
There are applications where finding and testing every edge case matters.
Often, though, a unit of testing time is better spent elsewhere.</p>
<p>A surprising benefit of this approach is that it keeps me focused on the question of how I can actually make sure the software <em>works</em>.
The surprising part is that we can lose focus on that question in the first place. 
But we can. 
It's all too easy to become a fanatic about testing in <a href="https://www.google.com/search?q=santayana+fanatic+redouble+efforts+source">the Santayana sense</a>, "redoubling your efforts when you have forgotten your aim."</p>
<p>Relatedly, Okken and Wisti make a point I think is underrated: learn coding by coding smoething that matters to you. 
If you are doing something you care about, it's easier not to forget your aim, and to avoid that sort of fanaticism. 
They even echo one of my examples: using Pytest to make sure links work. </p>
<p>Wisti seems to be on the same journey that, for me, terminated in writing my own SSG. 
("Terminated" in the sense of "continuing indefinitely, but more pleasantly.")</p>

Listening notes: Test and Code 191

<h2>Notes on writing a static site generator</h2>
<h3>Why write a static site generator?</h3>
<ol>
<li>Because <a href="https://www.natemeyvis.com/on-dependencies-in-small-projects">dependencies in small projects</a> are overrated.</li>
<li>For Marie Kondo reasons. It makes writing and maintaining my site pleasant and joyful. Other SSGs might be fine pieces of software, but they decidedly did not spark joy <em>for me</em>.</li>
</ol>
<h3>What have I learned?</h3>
<ol>
<li>Addressing some problem you actually have remains <a href="software-faq.html">a great way</a> to learn software.</li>
<li>Here's a testing philosophy: "Test the formal correctness of smaller parts of your code with suites of small tests. Test that these parts are interoperating correctly, and handling the right data, with other tools: smoke tests, dashboards, etc." You probably don't literally believe this, but a lot of us default to something like it. The SSG has, instructively, obliterated this view. Pytest is a wonderful tool for, e.g., ensuring that all my (relative) links work.</li>
<li>The SSG should be able to handle tens of millions of words or tens of thousands of posts. Not more, ever. (Alas.) The <em>site</em> might need to handle unpredictable and large scale, but <em>its construction</em> won't. Utterly divorcing "this is well-made software" from "this software can handle arbitrary scale" has been instructive. Remarkably few problems go away!</li>
<li>In many applications, separating the logical form of data from its persisted form is essential. Here, less so. I went down a wrong path of instinctively applying some patterns to accomplish that. It was an instructive failure, both psychologically ("why did I do that so reflexively?") and technically ("why don't I need this here?").</li>
<li>More generally: my other work is not <em>at all</em> like writing an SSG. Taking on a <em>real</em> project with a new structure has been eye-opening. I often see advice to stay sharp by learning new languages or new tools, usually with toy projects or tutorials. I find it much more illuminating to do diverse and <em>real</em> projects--usually, but not always, with the tools I know. The cognitive benefits of tackling a real problem are (for me, at least) much greater than those of exposure to a new tool. And I find it natural and pleasant to let technical needs in real projects drive me to learn a tool, rather than vice versa.</li>
</ol>
<p>However many rough edges remain, the project is a success. I have a tool I can use and improve indefinitely. And it really hasn't taken <em>that</em> much longer than learning to use some existing SSG. I am struck by how many Web sites outgrow the software they're made from (or seem indefinitely and tragically constrained by that software). I'm pleased to eliminate that category of problems.</p>

Notes on writing a static site generator

<h2>On estimating the value of GitHub Copilot</h2>
<p>Forget, for a second, whether GitHub Copilot is sustainable or not, ethical or not, and so on. 
What's it <em>worth</em>? 
That is, supposing Copilot functions as advertised and is legal and ethical to use, how much does it help a programmer?</p>
<p>I suspect this value is overstated, both in general and (especially) among people who are excited about AI. 
That's because people are misunderstanding the value of autocomplete. 
More powerful, but less predictable, autocomplete is only a good tradeoff if the "more powerful" is <em>way</em> more powerful and the "less predictable" isn't too bad:</p>
<ol>
<li>Most importantly: the way we generate value is by writing maintainable, intelligible code. The time savings of a great autocomplete are usually single-digit seconds. The time costs of having something that nobody ever properly understood in your code base are easily measured in the tens of hours. It doesn't even have to be a bug: it could be something needing changing in the ordinary course of development. This way of thinking is a crude simplification--there are more possible outcomes than these two. But when the bad outcomes are four orders of magnitude worse than the good outcomes are good, they better be <em>very</em> rare. Much rarer than Copilot's will be.</li>
<li>The time savings of autocomplete is less important than its ability to keep you in a flow state. Less predictable autocomplete is likelier to break your flow.</li>
<li>The cases where Copilot can offer the biggest savings--efficient generation of boilerplate code--are likely to be less relevant over time. Better frameworks and better development practices will (we may hope) remove more and more of these tasks. And if they don't, IDEs are likely to provide better support for boilerplate generation by traditional means. You might disagree with some of this; the broader point is that AI does not have as distinctive an edge in the case of snippet / boilerplate generation as it does in other applications.</li>
<li>The best users of Copilot are likely to be expert users of other autocomplete tools; this also diminishes the value Copilot provides.</li>
</ol>
<p>Note that the above arguments do <em>not</em> apply to DALL-E or other exciting AI / ML tools, which have very different payoffs and risks, and which replace very different kinds of workflows. My argument is not that AI <em>in general</em> is too risky to use, but rather that Copilot is fighting excellent alternatives and tackling a problem with an unfavorable cost-benefit profile for AI.</p>

On estimating the value of GitHub Copilot

<h2>On studying for your upcoming job: objections and replies</h2>
<p>Here I collect objections that arose <a href="https://news.ycombinator.com/item?id=31856512">on Hacker News</a> in response to <a href="https://news.ycombinator.com/item?id=31856512">this short argument</a>. Thanks to everyone who replied.</p>
<p><em>Q1</em>. "But of <em>course</em> studying a language is good!"</p>
<p><em>A1</em>. Yes, it is. 
Mastering a language is wonderful, and being totally ignorant of the language you'll be using is bad. 
The question I was answering, however, is whether a given hour is more efficiently spent learning a language or a tool, supposing you want to use that hour to prepare for an upcoming job. 
For the reasons I lay out, and especially because it's very hard to predict which parts of a language will be used and how, studying tools is likely a better bet.</p>
<p><em>Q2</em>. "Everyone should know [language <em>X</em>]."</p>
<p><em>A2</em>. See <em>A1</em>. 
Also, here as elsewhere, you can't infer from "any programmer would benefit from knowing <em>X</em>" to "every programmer should learn <em>X</em>." 
The latter requires an argument that <em>X</em> is not just good but better than anything else a programmer should be doing with that time. </p>
<p><em>Q3</em>. "If you ask the hiring manager how to study the language, you'll be studying just what you need."</p>
<p><em>A3</em>. Yes, this is better than just guessing.
But the hiring manager (i) might not know exactly how the language is used and (ii) often has strong incentives to oversell the quality of the existing code base.
The last time I tried this, <em>Effective Java</em> was recommended to me.
The Java I encountered was... not "Effective."</p>
<p><em>Q4</em>. "This is just your experience."</p>
<p><em>A4</em>. I should have been clearer about this. 
Although I've made this mistake many times, I'm not just writing about myself but about many other people I've seen do this. 
The impetus for writing this up was a person asking me what they should do to learn language <em>X</em>, having accepted a job offer to work in that language. 
So, this doesn't come out of rigorous research. 
But it's definitely not just me.</p>
<p><em>Q5</em>. "But in Python, there <em>is</em> only one good way to do things."</p>
<p><em>A5</em>. That's less true than people say, and less true than it used to be. 
(Just one example: whatever else you think of <a href="https://peps.python.org/pep-0622/">structural pattern matching</a>, it creates more ambiguity about which is the best tool when.)
More importantly, most code is not written "the good way."
Yes, be ambitious and aim to improve things.
But you will be working on the code base you have, which is probably not the code base in which everything is done properly.</p>
<p><em>Q6</em>. "This doesn't apply to the very basics of a language."</p>
<p><em>A6</em>. That's probably true, and I should have been clearer. 
Having some basic fluency in the languange will help.
(This is a great use of spaced repetition, by the way.)
But beyond "some basic fluency," the argument still applies.</p>
<p><em>Q7</em>. "My team <em>does</em> use language <em>X</em> beautifully and idiomatically."</p>
<p><em>A7</em>. Great! 
Good for you (sincerely). </p>
<p><em>Q8</em>. "But the use of a tool is as idiosyncratic and unpredictable as the use of a language."</p>
<p><em>A8</em>. The premise is false. 
There are different ways to use various tools. 
But it's pretty hard to study Bazel or Splunk or Jenkins or whatever without learning things that will help you basically anywhere those tools are used. 
Databases are, arguably, an exception here. Those get used all sorts of ways.</p>

On studying for your upcoming job: objections and replies

<h2>A common trap for people entering programming jobs</h2>
<p>In my first programming job, I was given <em>The C Programming Language</em> and told to study it. So when I got my second programming job, I figured out what language I'd be coding in and started studying up.</p>
<p>This was a mistake. Supposing you want to study for a job before you start the job, language study is almost always the wrong place to put your hours:</p>
<ol>
<li>If it's not a company-specific language, its range of use and ecosystem are probably so big that you can't know which parts of it will be used on the job.</li>
<li>And there will likely be specific libraries or tools that make using the language very different inside the company than outside of it.</li>
<li>There will often also be rules about which parts of the language you're allowed to use, and how. 
At my first BigCo job, I quickly realized that using C++ inside the company was more similar to using Java inside the company than it was to using C++ outside of the company.</li>
<li>With all respect: If you learn modern, beautiful, idiomatic use of some programming language, you're probably not going to see it on the job. 
It's good to know how the language is written under ideal conditions, but you'll still need to work with the code base you've got.</li>
</ol>
<p>Meanwhile, there <em>is</em> a likely source of confusion you <em>can</em> often address in advance: tooling. Ask about what the team uses for:</p>
<ol>
<li>Version control;</li>
<li>Testing;</li>
<li>Deployment / continuous integration;</li>
<li>Databases; and</li>
<li>Log management and search.</li>
<li>Metrics (thanks, <a href="https://news.ycombinator.com/reply?id=31858318&amp;goto=item%3Fid%3D31856512%2331858318">dukodk</a>!).</li>
</ol>
<p>Sometimes these will be proprietary, and sometimes they will not exist. 
But often they will (exist and) be things you can read about and even practice with. 
I have always found this sort of thing much harder to pick up than a new language.</p>
<p>If you have only ever worked on small- to medium-sized projects and are about to join a company, consider reading <em>Software Engineering at Google</em>. 
Whether or not you're going to work at huge scale, and whether or not you like all the recommendations in the book, it's a wonderful menu of the <em>problems</em> that arise from any kind of real scale. 
Any chapter of that book would have been more valuable to me than all the C++ prep I did back in the day.</p>
<p>P.S.: This post is about what to do <em>if</em> you want to study for a job before you start it. I'm ignoring the question of whether such study is good, bad, appropriate, or whatever else.</p>
<p>P.P.S.: Follow-up <a href="on-studying-for-your-upcoming-job-objections-and-replies.html">here</a>.</p>

A common trap for people entering programming jobs

<h2>Rubber duck text editing</h2>
<p>I'm still using and loving Vim, and still believe that most advice about learning it <a href="on-learning-vim.html">doesn't work very well</a>.</p>
<p>A few new points of disagreement:</p>
<p>Too much emphasis is placed on speed. Vim is fast, and that's great, but users will feel enough pressure to go fast on their own. It's probably counterproductive to say or imply that hesitation is the sign of a weak user.</p>
<p>This is particularly true because it will push new users away from learning and toward trying to type the things they know faster. It's hard enough to communicate just how big and feature-rich it is.</p>
<p>Relatedly, but conversely, <code>vimtutor</code> (which I respect and like) and other beginners' tools should do more to make beginners at least aware of tools like the jump list, the change list, marks, and the quickfix list. They probably won't use all these tools very soon. (Probably most <em>seasoned</em> Vim users don't use all of them.) But they are great tools for giving people a sense of what Vim is all about and what it can do. So, instead of introducing a complicated and metaphysically dubious notion of a "grammar of Vim" or similar, which can leave learners feeling like they are missing the point if they don't intuitively grasp (e.g.) which commands take a count and which don't, we could just say things like: "There's this thing called the jump list; it lets you go back to the last location you jumped from, and the one before that, and so on, back and forth, as you wish."</p>
<p>I suspect that the deeper mistake here is assuming that users need to be fluent in the exact definition of <em>X</em> before showing them a feature involving <em>X</em> (so, that they need to know the definition of a jump, a change, or a motion before they can be shown tools that use these concepts). It's an intuitive thought, but I think it's wrong in this case. Probably nobody knows, for every service they use that supports undo functionality, the exact rules governing how actions are chunked into units for the purposes of that functionality. They still ought to know that undo exists.</p>
<p>The best mental adjustment I've made recently as a Vim user is, when I hesitate or get a little confused, to ask myself: "What do I want to do?" Whether or not I'm interested in Googling to learn a new Vim thing right then, just saying it to myself tends to lead me to a good answer. (Often it's something like: "Go back to that file I just had opened" or "put an asterisk in front of each of the next 8 lines.") It's like <a href="https://en.wikipedia.org/wiki/Rubber_duck_debugging">rubber duck debugging</a> but for editing text instead of coding.</p>

Rubber duck text editing

<h2>Listening notes: The Pragmatic Programmer</h2>
<p>The audiobook for <em>The Pragmatic Programmer</em> is everything that an audiobook, and especially everything that a <em>technical</em> audiobook, should be. I love to listen to stuff about software, but a lot of it doesn't suit the medium well. A lot of thought went into this: the narrator is excellent, some passages are read by the authors, and the code snippets are adapted to the audio format with good judgment.</p>
<p>Satisfyingly, this is not just an authorial but a <em>programming</em> success; the book itself is used as a case study in how to use text as a single source of truth, how to parallelize parallel problems, and how to do the reasonable thing even if it annoys your publisher.</p>
<p>It's easily the single best technical audiobook experience of my life.</p>
<p>The content is also excellent: this is a true revision of the original. It mixes "wisdom of the ancients" and "current expertise" far better than I expected it to. (Not all rereleased classics of programming literature hold up.)</p>
<p>I endorse most, by far, of what's in the book. Two quick points of disagreement:</p>
<ol>
<li>Some of their recommended "descriptive names" (e.g., "buyer" for "user") seem dangerous to me. I'd rather maintain a focus on what the thing <em>is</em> rather than what it's <em>doing right now</em> in your code. My stock example here: if I'm writing a program to order pizza, and I currently order pizza on all and only Thursdays, I should still name the thing in my code <code>pizza</code>, not <code>thing_ordered_on_thursday</code> or <code>thursday_pizza</code>. In the <code>buyer</code>/<code>user</code> case, I fear that the code might change so that a <code>buyer</code> is also a shipping recipient, a notification recipient, or something else. Many problems are caused by names that are not descriptive enough, but many are also caused by things named according to accidents of their original context, not their real essences.[1]</li>
<li>The authors repeat fairly standard advice about using the power of Unix <a href="https://en.wikipedia.org/wiki/Pipeline_(Unix)">pipes</a> and generally about the power of viewing programs as extended transformations. I agree about the power of the paradigm, but I'm more skeptical about its limitations. Chaining together a ton of shell programs with pipes is almost impossible to test, and I think tests are valuable even in very small projects. Also, and relatedly, this usually requires intermediate values to be coerced into textual formats. That's often fine (or even desirable--see the chapter on "The Power of Plain Text"), but very often I'd rather have a program pass structured (and tested!) objects around. Finally, and at the risk of offending functional-programming acolytes, the paradigm of viewing all programs as transformations can be a Procrustean bed. But that's a longer argument.</li>
</ol>
<p>[1] There's a counterargument here that roughly goes: if a thing takes on other roles, it will be in a different <a href="https://martinfowler.com/bliki/BoundedContext.html">bounded context</a>, so the other name will be for a legitimately different object in a different context, and the original (more specific--e.g., "buyer") name will after all have been apt. Perhaps such an argument is correct, but that's not the argument the authors give.</p>

Listening notes: The Pragmatic Programmer

<h2>15 notes on testing software</h2>
<ol>
<li>If there is a One True Way to test software, we can't know what it is until we know a One True Way to design software.</li>
<li>But we don't know such a One True Way.</li>
<li>So, for now, it's more productive to think about empirical, surface-level claims about testing. (That's why this list is not an essay.)</li>
<li>Most of the world's production software is not tested.</li>
<li>The difference between "tested at all" and "not tested at all" is much bigger than the difference between "tested really well" and "tested at all."</li>
<li>Whereas the main practical difficulty in software is getting people to write software <em>well</em>, the main practical difficulty in software <em>testing</em> is getting people to write tests at all.</li>
<li>So beware of instituting any policy that could be willfully misinterpreted in a way that will cause fewer tests to be written.</li>
<li>And beware of responding to having poor test coverage by thinking about how ideal tests look instead of the motivational causes of proper tests' not getting written.</li>
<li>Bug-report templates with too many required fields discourage people from reporting bugs and distract them from communicating what's most relevant. </li>
<li>So optimize your bug reporting to <a href="on-task-management.html">make capture easy</a>.</li>
<li>If you're picking an aspect of discipline to develop, choose "actually goes and writes the test when something fails, even in development" over "writes beautiful and comprehensive tests for whatever thing I'm actually writing tests for."</li>
<li>Pytest is great.</li>
<li>When there's a performance problem with tests, most of the problem usually comes from just a few tests (or a single technique for setting up a fixture).</li>
<li>So a little profiling can go a long way.</li>
<li>And "I don't want to slow down the test suite" is not a good reason not to write that extra test.</li>
</ol>

15 notes on testing software

<h2>A quick argument for naming all software prototypes after birds</h2>
<ol>
<li>Software ought to have a memorable name.</li>
<li>It's good if software has a name that accurately describes what it does, but it's bad if it <em>inaccurately</em> describes what it does, and the magnitude of the badness of the mis-description is usually much larger than the benefit of an apt description.</li>
<li>It's hard to predict how software will evolve.</li>
<li>So a basic expected value calculation, in light of (2) and (3), suggests that software should not be given a <em>descriptive</em> name from the start.</li>
<li>And it's best not to spend too much time thinking about a prototype's name.</li>
<li>There are lots of birds, with names that are memorable but not descriptive, and it's easy to find long lists of bird genera.</li>
</ol>
<p>It's my <code>["foo", "bar", "baz", ...]</code> of software naming. And note that you can pick a name that evokes the idea of what you intend the software to be, without limiting it.</p>

A quick argument for naming all software prototypes after birds

<h2>An argument from Jimmy Koppel</h2>
<p>Jimmy Koppel has, in various places (see <a href="https://www.natemeyvis.com/software-design/">here</a>), advanced pieces of an argument that is significant enough to deserve an independent reference.</p>
<p>Let an <em>interface</em> be a specification of what a given bit of software does (and not, e.g., some abstract class appearing in code).</p>
<h4>Premises</h4>
<ol>
<li>There is a many-to-many relationship between implementations and interfaces.</li>
<li>What the code <em>really is</em> and <em>really does</em> is determined (at least in part) by its interface. In Koppel-ese, code has <a href="https://www.pathsensitive.com/2018/01/the-three-levels-of-software-why-code.html">a logical level</a>.</li>
</ol>
<h4>Conclusions</h4>
<ol>
<li>Specifying the behavior of an implementation cannot (entirely) specify what the code really is.</li>
<li>Guaranteeing (e.g., through testing) a set of implementation behaviors cannot guarantee that the code is correct.</li>
<li>The provable guarantees of the formalization (e.g., through a type system) of an <em>implementation</em> of an object do not <em>ipso facto</em> extend to <em>what the implementation represents</em>. The <a href="https://www.pathsensitive.com/2018/01/the-design-of-software-is-thing-apart.html">stock Koppel example</a> helps here: suppose you have an object that returns True iff some internal internal field is at least 65. All the formalism in the world won't distinguish between its being an ASCII alphanumeric-character checker and its being a retirement-age checker, and therefore won't verify that it is a correct implementation of (either) an ASCII character checker or a retirement age checker.</li>
</ol>
<h4>Occasionally useful alternative formulation</h4>
<p>All you can test about an implementation is a current, actual set of behaviors. But current, actual sets of behaviors implement many interfaces, in general, because interfaces also include counterfactual behavior (most commonly, behavior under future changes).</p>
<p>And counterfactual difference matters, because code needs to be <em>maintained</em> and should also be <em>semantically correct</em>.</p>
<p>So constraining, verifying, and testing implementations in general fails to constrain, verify, and test it <em>as an implementation of the interface</em>.</p>
<p><em>Thanks to <a href="https://www.robertbeard.info">Robert Beard</a> for helping me clarify this. As always, all mistakes and infelicities are entirely mine.</em></p>

An argument from Jimmy Koppel

<h2>How I got into programming</h2>
<h3>My story</h3>
<p>In the early 2010s I was a gradate student in philosophy. I read about <a href="https://projecteuler.net/">Project Euler</a> somewhere and realized that programming was (i) interesting enough to try and (ii) would cost $0 given that I already owned a computer. Project Euler was itself fun, and (more enduringly) I fell in love with Python.</p>
<p>A college friend was working for a bioinformatics startup needing a documentation writer. Needing to choose between (i) leaving Boston for a TAship in Ithaca, NY or (ii) making money some other way, I chose (ii) and got the documentation job. Everyone involved was eager for me to spend some of my time learning the details of algorithms relevant to bioinformatics, so it was a good environment to learn to code.</p>
<p>(There's a familiar story among programmers: "In my course work I was led to believe that programming was all about learning algorithms and data structures. When I started my career I immediately found myself using only basic algorithms; the hard part was learning tools and systems." I had something like that experience, but delayed: my first job thoroughly <em>reinforced</em> the impression that fancy algorithms were absolutely central to industrial work in programming.)</p>
<p>Startups tend to be flexible places, and I took on a lot of jobs within that company, including first-order work as a programmer. Eventually I went out on my own as a consultant, then took a job at Google, then did various other things. But that's of much less interest to most people who ask me about this. The most relevant aspects of this story are:</p>
<ol>
<li>I learned from MOOCs, books, and experimentation.</li>
<li>I started on a lark.</li>
<li>It was a bit less than a year between starting my independent part-time studies and having some sort of job in software.</li>
<li>It was about six months after that that I was in some sense working as a programmer.</li>
<li>I got my first job by (i) being willing to work at a startup and (ii) having a very good personal connection at one.</li>
<li>And my first job was "programming-adjacent."</li>
</ol>
<h3>Postscript</h3>
<p>That is, I said, <em>my story</em>. It's true and it's what I said in all sincerity, for years, to people who asked. It's incomplete, though. I was in high school from 1997 to 2001. Some friends of mine were into computers; there were a couple computer classes available; and I carried around a programmable TI-83 calculator all day.</p>
<p>I can't say how much programming I did then, but it must have been a lot: I remember spending hours programming, e.g., a simple version of craps. And I wrote a units-conversion program. The latter was my first experience releasing and versioning software: I chased down the one person who self-identified as a user of it and asked to borrow his calculator so that I could attach it to mine with a cable and give him a version of the program with a bugfix.</p>
<p>It is easy to recall many memories of myself being totally engrossed in programming. I omitted from the narrative above because I omitted it from my narrative <em>then</em>: I was a math guy, trivia geek, runner, and so on. (Or so I thought.) I never so much as considered a CS class as an undergrad and never talked about myself as a programming enthusiast.</p>
<p>So, I spent a bit over a decade paying no attention to programming. And the most relevant facts <em>here</em> are that:</p>
<ol>
<li>If you asked me about my programming background, and I told you it all started in my grad school years, I wasn't quite getting it right;</li>
<li>But I wasn't <em>lying</em>; I had really just not allowed that part of my youth to enter my self-concept.</li>
<li>The more accurate version of that first point above is: I learned from MOOCS, books, and experimentation, where "experimentation" includes a lot of fumbling around with TI-83 programming and BASIC in the Clinton administration.</li>
<li>The human capacity for self-deception is enormous.</li>
</ol>

How I got into programming

<h2>Notes on a Bryan Cantrill talk</h2>
<p>So! Bryan Cantrill (who, it turns out, <a href="https://en.wikipedia.org/wiki/Bryan_Cantrill">has a Wikipedia page</a>) gave <a href="https://www.youtube.com/watch?v=30jNsCVLpAE">a talk</a> at GOTO 2017. It deserves to be seen more than a five-year-old conference talk figures to be. Some notes:</p>
<ol>
<li>For Cantrill, debugging is the process of <em>asking questions of a system</em> (and not, primarily, attempting to <em>fix</em> a system). This reminds me of Michael Feathers' view of testing as primarily about describing what a program does (and not, primarily, of enforcing its correctness).</li>
<li>Therefore, debuggability is the propensity of a system to have questions asked of it. I think about this in Socratic terms. When you're doing intellectual work, you of course need to have ideas to talk about. But you also need to be in the right condition to pose and answer questions in light of those ideas. That system of questioning is the more fundamental thing. (In grade school I was taught that The Scientific Method requires one to formluate hypotheses strictly before looking at data. This view seems totally archaic.)</li>
<li>Relatedly: suppose <em>X</em> is causing an incident in a distributed system. Given that, you'd like to have an alert for <em>X</em>. It does not follow that you should have tons of alerts all over the place! Humans are not very good at inferring from alerts to causes in the first place, and this ability degrades quickly with the number of alerts to process (<a href="https://www.youtube.com/watch?v=gO8N3L_aERg">video link</a>). eThis is not quite how Cantrill puts the point.)</li>
<li>We can learn about distributed systems incidents by looking to history, and not just the history of computer distributed systems. (Cantrill has a useful discussion of <a href="https://en.wikipedia.org/wiki/Three_Mile_Island_accident">Three Mile Island</a>.)</li>
</ol>
<p>Some people react to intellectual challenges by reciting everything they know; others are great interlocutors. Whom would you rather be working with in an emergency?</p>

Notes on a Bryan Cantrill talk

<h2>On Anki's database</h2>
<p>I am a daily spaced repetition user (I describe how and why <a href="on-using-anki.html">here</a> and <a href="on-using-anki-again.html">here</a>). I've been working with my Anki data lately, which has meant exposing and manipulating the <a href="https://www.sqlite.org/index.html">Sqlite</a> database underlying the program. (I'm grateful to the <a href="https://github.com/ankidroid/Anki-Android/wiki/Database-Structure">Ankidroid project</a> and <a href="https://www.reddit.com/r/Anki/">r/anki</a> for having documented so much about the .apkg format and the database itself.)</p>
<p>The database structure is fairly typical of data management in long-running projects. And, typically, some of its design looks rough to fresh eyes. When fresh eyes see rough parts of a software project, <a href="https://danluu.com/wat/">it's important to write about it promptly</a>, and the Anki community is large and dedicated enough that it seems worth doing that writing in public. So here's what I think could be better.</p>
<p>By the way, <a href="https://www.itsinks.in">It Sinks In</a> is an attempt to address some of these issues with a user-friendly, cloud-based approach.</p>
<h4>Caveats</h4>
<ol>
<li>Anki is, I think, maintained by a very small team. Some of the notes about the intelligibility of the schema matter less if there aren't many people who need to work with the database every day. You can think of the relevant notes as things that are merely suboptimal now and <em>would</em> be more damaging <em>if</em> the Anki project were to grow.</li>
<li>The underlying database is, I think, not (or at least not primarily) intended for direct manipulation by program users. So there's a sense in which it doesn't matter very much how intelligible I think the data management is. That said, insofar as it affects the accuracy or performance of the software, it certainly matters. And given that people turn over parts of their minds to Anki, it's especially urgent to document these things.</li>
<li>Anki is great and all this comes from a place of love.</li>
</ol>
<h4>Principles behind these notes</h4>
<p>You can think of this as a data-oriented extension of my code review reference; this is all stuff I find myself saying <em>a lot</em>. Seeing so many of these issues crop up in Anki's database was one impetus for making a case study of it.</p>
<ol>
<li>Try to name columns (or tables, or documents, or whatever) according to <em>what the thing is</em>. Not its domain, not what you want it some day to be, and not even its intended use, but what it <em>is</em>.</li>
<li>Unless you have a very good reason to <em>denormalize</em> your data, represent a given piece of information at most once in your database.</li>
<li>Unless you <em>really</em> need to optimize something, make a given column represent only one piece of information. (You know those surveys where you rank things on a 1-7 scale, but "4" also means "not applicable"? Do better than that.)</li>
<li>All else equal (and sometimes even if not), use consistent conventions (e.g., for naming, for delimiters, and for <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUIDs</a>).</li>
</ol>
<h4>Notes</h4>
<ol>
<li>In the <code>cards</code> and <code>notes</code> tables, the <code>id</code> (primary key) field is the number of milliseconds since the epoch when it was created. There are good reasons not to have semantically meaningful information in the <code>id</code> field: in this case, it is entirely possible for several <code>cards</code> to be created at the same millisecond. (The foreseen use case is that of a single human creating cards manually, but what if the system scales to many users with many cards? What if cron jobs that go off at midnight generate new cards? What if cards are created from timestamps that only have second-, hour-, or day-level resolution?)</li>
<li>In the <code>cards</code> table, the <code>type</code> and <code>queue</code> columns duplicate information and both express what I'd be tempted to call a "learning status" (whether the card is new, is being reviewed, is buried, and so on). The database would be cleaner with these collapsed into a single column with a better name.</li>
<li>In the <code>cards</code> table, several columns have integers representing times or durations for which the units are different depending on some other feature of the card. For example, the <code>due</code> column is an integer representing either a number of days or a number of seconds, depending on the card status. I could imagine a case for splitting this out into separate columns. It's also worth considering not explicitly storing the data at all, because it's a function of other data (and the learning algorithm). Because most decks are not huge, it could probably could be calculated on demand (or, if it really needs to be precomputed, cached elsewhere).</li>
<li>The <code>cards</code> table has a <code>reps</code> column indicating its number of repetitions. This duplicates information from the <code>revlog</code> table. One could imagine a situation where information needs to be denormalized in this way, but (i) this system is clearly not designed for the sort of scale that would require that (see other notes) and (ii) if so, it would probably be better to keep "source of truth" <code>cards</code> data in a separate table and generate separate denormalized views or tables. Similar comments apply to the <code>lapses</code> column.</li>
<li>The <code>flags</code> field is only significant mod 8: mod-8 values correspond to various colors of flags or no such flag. This rules out the possibility either of a card's having several flags set or of there being more than 8 flag-states. Moreover, coders accustomed to "flags" fields will likely anticipate a system where bits of a binary representation correspond to flags' being set. Given that this is an integer field in either case, little would be lost and much gained by adopting a more standard system for representing flag values.</li>
<li>There is a <code>graves</code> table representing cards, notes, and decks that have been deleted. This is awkward. First, it combines heterogeneous data (data that are different not only in representing different categories of items but also in actually being stored in separate tables in this database when learning circumstances are different). Second, it amounts to moving data from one table to another in the case of a status change; it is usually better to simply make such a change like that in existing status fields. (I often find that solutions like this are attempted compromises by programmers who are pretty sure, but not completely sure, that data should be deleted. It is almost always better to settle that question once and for all--by literally deleting it, by leaving it, or by sending it off to some archive or backup--than to attempt this kind of compromise.)</li>
<li>The relationship between <code>notes</code> and tags is represented by a text column on <code>notes</code> with a list of tag names, both separated by spaces and with spaces at the end (in order to support <code>LIKE "%tag%"</code> queries, according to the Ankidroid documentation linked above). This is an error-prone way to represent a many-to-many relationship. I'm not an SQLite expert, but I'd imagine it's inefficient, too. More fundamentally, tags are clearly domain objects that should be properly represented (and probably need their own table). Whenever I've tried to keep track of objects like this <em>ad hoc</em> as strings--and I've tried this many times!--I've regretted it. (Do as I say, not as my past self has done.)</li>
<li><code>flds</code> (representing a many-to-many relationship between <code>notes</code> and fields) is represented similarly to <code>tags</code>, but separated by <code>0x1f</code>. The comments above apply, and there's an extra bit of potential confusion because the delimiter is different here. An aside: in this case, using <code>flds</code> instead of <code>fields</code> appears to be abbreviation for abbreviation's sake, and nothing more. But I often find that abbreviations like this, especially when nearby objects are <em>not</em> abbreviated, correspond to misalignments between the abbreviated word and the data object. So, for example, <code>tmstp</code> might abbreviate "timestamp" but actually mean something closer to "a timestamp but not really." When you read code, get in the habit of asking whether abbreviated names are subconscious (or conscious) expressions of the fact that the name isn't quite right.</li>
<li>The <code>csum</code> ("checksum") field on <code>notes</code> is (apparently) intended for uniqueness checks. (It's not clear that this is literally a checksum; see point (8).) This function would be better served by using built-in mechanisms for creating unique <code>id</code>s. (More generally, database software is pretty good at primary key management and generation. Programming is hard enough; leave this sort of thing to the software.)</li>
<li>In the <code>revlog</code> table, the <code>time</code> field represents a duration, is capped at 60s, and is represented in milliseconds. It's usually best not to throw away information. (Are you so sure you won't <em>ever</em> care about the difference between 65 and 75 seconds?) Moreover, this is not a time but a <em>duration</em> and should be so named. And it would probably be best simply to store the beginning and end timestamps of the review and let the calculations be done downstream: this is a subtle form of storing several pieces of information together.</li>
</ol>

On Anki's database

<h2>On dependencies in small projects</h2>
<p>Dan Luu <a href="https://twitter.com/danluu/status/1434282810622291970">Tweeted</a>:</p>
<blockquote>
<p>The places where I most regret taking a dependency are often very low effort projects (like the SSG for my blog), where the complexity of the dependency wasn't worth it.</p>
</blockquote>
<p>I've chewed on this for three days. It feels like a <a href="https://www.reddit.com/r/slatestarcodex/comments/3st7e5/what_was_your_last_great_viewquake/">viewquake</a>. Some reflections:</p>
<ol>
<li>The survivor bias in the sample of "here's a thing I hacked together on a weekend" is obvious but easy to overlook.</li>
<li>Also obvious but easy to underestimate: there are strong social norms encouraging people to exaggerate (i) how fast they've shipped small projects and (ii) how well those projects work.</li>
<li>A <em>lot</em> of small projects, certainly including those that rely on a dependency the way a personal site relies on a static site generator, do not survive. I have lots of first- and third-personal evidence here.</li>
<li>Most dependencies that are maintained well enough to avoid crippling bugs also add features regularly. Over time, and often despite maintainers' best efforts, this can make basic "plug and play" usage harder.</li>
<li>Small projects, not just in software, are harder to pull off than they seem. So here's another way to frame the point I take Dan to be making: Let's say a project seems small. You do it without taking on a dependency, and it's basically a success, but it took more effort than it seemed it should. So we have extra effort to account for, and at least two possible causes: (i) the actual intrinsic difficulty of the project and (ii) the fact that you didn't get a boost from the dependency. Because we underestimate (i), it's natural to overestimate (ii).</li>
</ol>

On dependencies in small projects

<h2>On dependencies</h2>
<p>If I could give four words of instruction to an unknown intermediate-level programmer, I'd probably go with "think about dependencies more."</p>
<p>It's remarkably hard to keep track of what exactly you're thinking about when you're thinking about dependencies. There are at least three candidates:</p>
<ol>
<li>There are dependencies at the file/package/module (depending on the system you're working in) level. When your compiler (or interpreter, or whatever) complains about a circular dependency, this is the kind of dependency you start reasoning about.</li>
<li>There are dependencies of objects on objects. So, when you read <em>Architecture Patterns in Python</em> and you read that your domain entities should be depended on and not depend on anything else, it's this kind of relation you're thinking about. But these discussions often occur at the code level, and there is also a logical level, so that:</li>
<li>There are dependencies of objects on objects at the logical level. So, for example, when you make a foreign key reference in a Django model <a href="https://docs.djangoproject.com/en/4.0/ref/models/fields/">with a string instead of the Model itself</a>, you avoid a dependency at the code level but retain it at <a href="an-argument-from-jimmy-koppel.html">the logical level</a>.</li>
</ol>
<p>There are a few immediate lessons here:</p>
<ol>
<li>It's easy to take yourself to be thinking about one kind of dependency and actually be thinking about another.</li>
<li>If you're making a dependency graph, be sure not to graph different kinds of relationships at the same time or unwittingly make the same box refer to, e.g., both a module and a logical object.</li>
<li>Devices that remove one sort of dependency might leave another sort of dependency, and the remaining dependency might be dangerous.</li>
</ol>

On dependencies

<h2>On editing text</h2>
<p>Here I assemble a bunch of things I believe, and find myself repeating, about text editors.</p>
<ul>
<li>Learning how to use your tools <em>well</em> is one of the two or three most underrated skills in software.</li>
<li>It's also one of the most underrated skills in computer usage (and by extension modern life).</li>
<li>It's very hard to learn from authority here, because (i) tool fitness is idiosyncratic, (ii) feelings get involved, and (iii) knowledge of an ecosystem is hard-earned but short-lived and often more local than one appreciates. (In this respect, advice about software tools is a lot like parenting advice.)</li>
<li>More specifically: many people will say that you are not A Real Programmer or A Real Writer until you know [some tool]. That is not true.</li>
<li>You can achieve large productivity gains from improving your use of a text editor.</li>
<li>But be kind to yourself. Learn in a <a href="https://www.natemeyvis.com/writing/backward-compatible-improvements/">backward-compatible</a> way. Do not shame yourself for, e.g., using a mouse even after you get a taste of the power of keyboard shortcuts.</li>
<li>I think PyCharm is great. I used it for a long time and will probably go back to it during coding sessions when I'm likely to need advanced refactoring support.</li>
<li>But I'm loving Vim these days for nuts-and-bolts coding--it's so <em>fast</em>.</li>
<li>And although PyCharm, like other modern IDEs, is a wonderful language-specific coding tool, I fear I was using it as a mediocre operating system.</li>
<li>E.g.: tab-completion doesn't work for me in its terminal. I've looked through some forums. Do I really want the burden of knowing stuff about <em>the PyCharm terminal</em>? Enough of my brain is consumed with knowledge about terminals. Once I chose not to use the integrated terminal, some fraction of PyCharm's functionality was not relevant to me. Similar things happened with the debugger, version control integration, and so on.</li>
<li>That said, I do not intend to maintain an extensive .vimrc. The extensibility of Vim is a sneaky weakness: it tempts you to bind your knowledge of a very secure, long-lasting tool to a bundle of ephemeral, indifferently tested ones. (You know that bit in "Sailing to Byzantium" where the narrator notes that his soul is "sick with desire / And fastened to a dying animal"?)</li>
<li>I'm increasingly convinced that the trick to choosing the right development environment is (i) not allowing learning about it to suck up too much of your time but (ii) giving yourself permission to learn progressively more about it without frustration. For a long time learning things about PyCharm felt like time well spent and learning about Vim felt like time spent badly. Now it's the opposite.</li>
</ul>

On editing text

<h2>On improving data-adjacent code</h2>
<p>Here's the most stimulating bit of feedback from <a href="on-ankis-database.html">the post about Anki's database</a>:</p>
<blockquote>
<p>My impression is most databases are designed fairly haphazardly, and while tables may have fields added, the entity relationship diagram stays pretty static. My rationale is as follows: (1) A database schema requires quite a bit of thought and up-front design, which we're loathe to do in this agile world; (2) Schema migrations are hard and scary, so we avoid doing them.</p>
</blockquote>
<p>--<a href="https://news.ycombinator.com/item?id=30439645">LAC-Tech</a> on Hacker News (lightly edited)</p>
<p>So: we get into the habit of defining structures on the assumption we can change them easily, but when databases are involved we <em>can't</em> change them so easily. This is an underrated problem; it's both technical and cultural. Here's how I try to mitigate it:</p>
<ol>
<li><em>Think about</em> persistence from the beginning, but delay <em>actually persisting</em> things until later. Use in-memory / mock versions of your persistence layer until you've had a chance to learn more about your objects.</li>
<li>Have ready sources of test data, usually flat files but sometimes functions that make mock data. Maintain functions that transform that test data into your current object representations, so that you don't have to change the underlying test data every time you change your object representation. (It's usually a lot easier, both mechanically and psychologically, to change those functions than the underlying data.)</li>
<li>Make the in-memory / mock versions of your persistence layer obey the same interface as your database-facing code will. This means that other parts of your code base should not need to know or care about persistence details. (The Domain-Driven Design folks are good at this.)</li>
<li>Make utilities that test, for anything implementing the interface described in (3), whether the data conforms to the current schema. Dashboards are your friend: it's usually not hard to calculate and display lightweight analytics. Having a ready way to display a human-readable view of data samples is often invaluable. </li>
<li>Add tests that feed the data from (2) through whatever CRUD functions you're building, retrieve that data through the interface described in (3), and test the data with the utilities in (4).</li>
</ol>
<p>Different projects are different enough that these steps look different whenever you implement them. A common flow, however, is to have some utility function loop through <code>test/data/test_widgets.csv</code>, create a bunch of Widget objects, create a new widget persister and apply the current schema to it, pass the Widget objects into <code>widget_persister.add_widget()</code>, call <code>widget_persister.get_all_widgets()</code>, and run some tests on the result.</p>
<p>After I sketch out a design, I often build out parts of it roughly the way I'd implement a sand castle: by starting to put sand wherever I want there eventually to be castle. (It's not too hard to touch things up along the way, and the best way to know what to fix is to have built something that shows me what's wrong.) Persistence-facing parts work differently: it's the part of the sand castle where you have to leave the upside-down bucket in place of the tower for a while and just built around it.</p>
<p>This can be tricky, but it has clear benefits: it forces you to focus, for a while at least, on the interface the persistence layer will obey more than its implementation. Most of us <a href="software-design.html">don't think about interfaces enough</a>, so this makes for great practice.</p>

On improving data-adjacent code

<h2>On learning Vim</h2>
<p><a href="on-editing-text.html">I use Vim</a>. I like Vim. But for all that's written about learning Vim, most of it is not useful.</p>
<h3>Suggestions on learning Vim</h3>
<ol>
<li>Do not put painful restrictions on yourself or shame yourself for using the mouse. Learn enough to get going, and when you find yourself trying to do a certain thing over and over, look up how to do it. (I think Yehuda Katz <a href="https://yehudakatz.com/2010/07/29/everyone-who-tried-to-convince-me-to-use-vim-was-wrong/">got this basically right</a>.)</li>
<li><code>vimtutor</code> is great for learning enough to get going.</li>
<li>Installing a bunch of plugins is often a trap. This is especially true at the beginning, when it's more likely that the thing you're trying to accomplish is doable with vanilla Vim. Dependencies are terrible, <a href="on-dependencies-in-small-projects.html">even or perhaps especially in contexts like this</a>. Avoid them.</li>
<li>Vim is <em>huge</em>. It has more features than you think it has. Its speed and lack of a persistent menu add to this illusion. This means, among other things, that different users grow into using different subsets of the features, and come to find them fundamental. So: ignore most claims about which features of Vim are the fundamental ones.</li>
<li>Vim doesn't have a persistent menu, but its <code>:help</code> documentation is wonderful.</li>
</ol>
<h3>A note on human progress</h3>
<p>Much of the best stuff in computing comes out of small communities characterized by strongly held core beliefs, cultures of learning, and strong adherence to principle. Many could be described as "cult-adjacent." (The domain-driven design community has always struck me this way.) It's tricky to use artifacts from these communities, whether they be pieces of software or mental models, effectively. This is not the only case where the thing is worth learning but the dominant explanations for <em>how</em> and <em>why</em> to learn it are likely to mislead.</p>

On learning Vim

<h2>On preparing for coding interviews</h2>
<p><em>Q</em>: How should I prepare for coding interviews of a certain standard sort ("algorithms and data structures interviews," "whiteboard interviews," "Leetcode interviews")?</p>
<p><em>A</em>:
Do your best to mimic the actual environment of your interview:</p>
<ol>
<li>If possible, drill in the same IDE that you'll use in the interview.</li>
<li>Practice talking through the question (literally, out loud, at least sometimes).</li>
<li>If you won't be able to execute the code you write, don't let yourself do this as you write the code in practice.</li>
<li>But do go back and make sure you wrote code that actually works, whether or not you'll be allowed to run the code during the interview.</li>
<li>Do at least some of your practice in clothes like the ones you'll be wearing.</li>
</ol>
<p>Choose a few problems that (i) are a bit harder than will typically be asked and (ii) exercise a few essential skills (graph traversal, binary search, whatever). Do them repeatedly, as drills.</p>
<p>LeetCode is better as a question repository and discussion forum than as a platform for testing your answers. The platform will confront you with overflow / underflow cases and other edge cases that your interviewers will overlook, guide you through, or happily leave underspecified. It's good to know about (e.g.) overflow, but it's inefficient to spend so much practice time on it.</p>
<p>Definitely try to learn all the essentials, but not at the expense of becoming more fluent in areas you know pretty well. People sometimes spend 10 to 25 hours struggling with the tricker parts of dynamic programming or XOR hacks when they would be better off using that time to absolutely nail down basic graph search algorithms.</p>
<p>Practice the skill of plugging away at a problem when you're stuck, but treat it as one skill among many. So: don't spend too much time struggling when you're stuck. It's more important to learn all the basic question types.</p>
<p><em>Cracking the Coding Interview</em> is an excellent question repository (and a bit underrated as an instruction / reference book). <em>The Algorithm Design Manual</em> is a pleasant and very different sort of reference, with plenty of "aha" moments. But beware of the trap of substituting passive reading for active preparation.</p>
<p><a href="mailto:nate@natemeyvis.com">Email me</a> if you have other questions.</p>

On preparing for coding interviews

<h2>On quadratic complexity</h2>
<p>Many algorithms have quadratic complexity: sometimes this is necessary, but <a href="https://accidentallyquadratic.tumblr.com/">often it's not</a>. This and related facts are widely known but underappreciated. Quadratic complexity is a more pervasive phenomenon, and explains more other phenomena, than is generally recognized.</p>
<h4>Quadratic complexity is everywhere</h4>
<p>It often happens that you need to track some pairwise relationship for all pairs of objects in some set. These situations are more easily perceived when the objects are elements of an array. Sometimes, though, the objects are the components of a software system: here, "gluing" those components together generates tasks that are <a href="https://www.oreilly.com/radar/thinking-about-glue/">quadratic in the number of components you have</a>.</p>
<p>Within a component, one often sees quadratic complexity at higher levels than arrays. This is one reason it's so important to model your domain correctly: if, for example, you make something a property of <em>A</em> when it should be a property of <em>B</em>, the penalty is often that operations that formerly required checking all the <em>A</em>s <em>or</em> all the <em>B</em>s now require checking all the <em>A</em>s <em>and</em> all the <em>B</em>s. You're paying a quadratic cost across a larger domain. (Also, your code tends to be harder to reason about, because it's harder for your brain to invoke some hodgepodge of intuitions about <em>A</em> and <em>B</em> than either one individually--but that's a separate issue.)</p>
<h4>Quadratic complexity can explain other things</h4>
<p>We do (and ought to!) think about how fast exponential growth happens, but we sometimes forget that quadratic growth is pretty fast too. Think about an old riddle: suppose the scum on the surface of a pond doubles every day (growing exponentially), and at the end of April it covers the whole pond. When did it cover only 1/4 of the pond? April 28, two days before the end of the month.</p>
<p>Suppose the scum is growing quadratically: then, on the 28th, it's about 87% full. That's way more than a quarter, but less than intuition might first suggest.</p>
<p>If you're programming, and need to keep track of all the pairwise relationships in a set of items, it matters a lot whether that set has four or five things in it: that's the difference between 6 and 10 pairwise relationships. Whatever you think of the research about <a href="https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two">short-term memory</a>, 10 is a lot bigger than 6 as far as your "active brain" is concerned.</p>
<p>This can explain why getting stuck in programming can feel (i) so sudden and (ii) so intractable. At least sometimes, "why is this so hard to reason about now when it wasn't a minute ago" is answerable with: "because those two extra things you added generated another couple dozen relations (or cases to check or failure modes)."</p>
<p>If you've ever wondered why <a href="https://www.johndcook.com/blog/2011/11/22/norris-number/">Norris's number</a> exists: look here, perhaps.</p>

On quadratic complexity

<h2>Reading notes: A Philosophy of Software Design</h2>
<p>Aspects of the book that have stuck with me include:</p>
<ol>
<li>His firm belief that interfaces should be small; <a href="https://www.pathsensitive.com/2018/10/book-review-philosophy-of-software.html">it's not clear he's right about this</a>.</li>
<li>Many elegant examples, both from his teaching and his engineering.</li>
<li>The wonderful treatment of information leakage, including some subcategorization of the problem. (Very roughly, leakage can be divided into leakage through an interface and "back-door" leakage. Interface-based leakages can be divided into those that result from oversized interfaces and those from inadequate defaults. Back-door leakages can be divided into those resulting from the use of structural information in several places, those resulting from there being too many objects; and those resulting from other causes.)</li>
</ol>
<p>The sections below cover important topics from the book in slightly more detail:</p>
<h4>Design it twice</h4>
<p>Because designing systems is hard, Ousterhout recommends considering at least two designs before choosing one; see chapter 11.</p>
<p>Note that this is analogous to <a href="https://www.pokernews.com/strategy/take-a-cue-from-pool-consider-your-options-poker-23665.html">standard advice in cue sports</a>.</p>
<p>We can decompose this advice into (i) caring enough about getting the design right to put in a bit of extra effort and (ii) learning about something--in this case, a design--by asking "if this is wrong, how is it wrong?"</p>
<p>Re: (1), when you're reading a book about software design, it's easy to care about getting design right. But in industry, there are so many reasons to lose sight of it. A few of these are: the pressure of short-term bug fixes, the assumption that a system will naturally optimize itself over time, the difficulty of communicating about system design, and the fact that educations in software often neglect the sort of design in question.</p>
<p>Re: (2), for generality and power, that question has to be one of the most effective cognitive tools there is. (Its converse, "what follows from this if this is right?," is at least as powerful and is a core of <a href="https://philpapers.org/rec/MENPAT-3">the method of analysis</a>.)</p>
<h4>Investment rate</h4>
<p>Ousterhout recommends spending "about 10-20% of your total development time" on investments such as reconsidering class designs, improving documentation, and fixing bugs more deeply than is required to close a ticket. See sections 3.2-3.4.</p>
<p>This is a nice example of compounding returns paying off more quickly than we might suspect--and, therefore, of the more general phenomenon that people aren't good at estimating the effects of exponential growth.</p>
<p>I suspect that the right number is closer to 20%--actually, I suspect that the right number is <em>higher</em> than that. My investment rate even for "throwaway" projects is at least 10-15%, and surely investment gets more valuable when project time is measured in weeks and years instead of hours.</p>
<p>Although some software engineers truly don't believe that these investments are worth it, many suffer from lack of discipline either at the personal or organizational level. Here as elsewhere, modest improvements in discipline and culture can matter more than large improvements in engineering skill, narrowly construed.</p>
<h4>Pass-through methods</h4>
<p>A method that invokes another method, has a similar signature to it, and does not add much functionality to it. Ousterhout discusses the problem and argues that it is a red flag (see below) in section 7.1.</p>
<p>I don't have much to add to Ousterhout's excellent discussion except a speculative diagnosis: constructing layers of abstraction that are only subtly different is sometimes intended (and interpreted) as a sign of care and sophistication. (My code review reference contains a brief discussion of this, under "This layer of indirection...") </p>
<h4>Red flags</h4>
<p>These are discussed throughout the book and summarized in an appendix.</p>
<p>This might be the most valuable aspect of the book; fluency with a set of red flags is a big efficiency boost (especially in code reviews). I hope that other engineers will publish on the subject.</p>
<h4>Temporal decomposition</h4>
<p>The mistake in which "the structure of a system corresponds to the time order in which operations occur;" see section 5.3.</p>
<p>This mistake is vastly more common and more severe than acknowledged; if anything, Ousterhout doesn't do enough to emphasize it. (But by mentioning it at all, he does more than most.)</p>
<p>Related: if what you need to be reasoning about is a dependency graph, don't confuse it with a data flow diagram. (Do not confuse the dependency relation with the data-that-used-to-be-here-is-now-there relation.)</p>
<p>This bias extends beyond software. Perhaps <em>some</em> biographies should go through the life chronologically, but far too many of them do.</p>

Reading notes: A Philosophy of Software Design

<h2>Reading notes: Patterns of Software</h2>
<p>I'll probably never finish Richard Gabriel's <em>Patterns of Software: Tales from the Software Community</em>. The core of the book (or at least the first 1/3 of it) is a meditation on the career of <a href="https://en.wikipedia.org/wiki/Christopher_Alexander">Christopher Alexander</a> can teach us about software design.</p>
<p>Gabriel's turns of phrase tend not to land with me, partly because the technical discussion doesn't include examples or sufficiently precise argumentation about software. There are enough mechanical errors (at least in my edition) to distract the reader, and the structure of the book (a series of titled, related semi-essays) works against my attempts to synthesize the information.</p>
<p>But I'm glad this book exists. It reminds me of poker literature. When I studied poker most seriously, it was immature as a field of study, with an oral tradition of knowledge-transmission and enthusiastic practitioners. This led to a lot of technical and semi-technical writing that is unconstrained by traditional subgenre boundaries. Such projects don't always succeed or endure, but the practical alternative to this kind of artifact is usually not a polished, impeccably structured book but rather nothing at all.</p>
<p>So, in the case of Richard Gabriel, if someone loves software, loves architecture, and wants to write a long meditation on the connections between the ineffable qualities of great software and the career of Christopher Alexander, I really want that person to write that meditation. My life is better because <a href="https://www.amazon.com/Ace-River-Advanced-Poker-Guide/dp/0972044221">Barry Greenstein wrote something that reminds me of Seneca more than anything else</a>, Bob Ciaffone saw fit to publish <a href="https://www.amazon.com/Improve-Your-Poker-Bob-Ciaffone/dp/0966100700">occasionally speculative advice</a> back in 1997--and because poker literature was unsaturated enough to have some room for <a href="https://www.amazon.com/Thinking-Tournament-Poker-Nate-Meyvis-ebook/dp/B017MTTGYC/">my own self-published speculations</a>. It's also better because I picked up this book. I just can't finish it.</p>
<p>Some notes:</p>
<ol>
<li>Gabriel speaks of <em>habitability</em> in software design. Michael Feathers gives an related warning: "Remember, code is your house, and you have to live in it." Feathers is talking about hygiene where Gabriel is discussing something less tangible, and the continuity of the metaphor is striking. It has infiltrated my work: every day I think of myself as <em>living in</em> the software I work on.</li>
<li>Gabriel says that clarity "is just too rare, and it's dangerous too, in a funny way." This is nonobvious and correct (and I want to post it in every building where analytic philosophers work). Aristotle famously warns us to tailor the precision of our descriptions to the underlying subject matter: Don't settle for mere persuasion if you're discussing geometry, but also don't expect geometrical proof if you're talking about the weather. We want clarity in software, but only insofar as it's there to be achieved. Suppose an argument already has as much clarity as it's going to get. If you try to add more, something will go wrong: you'll think you're adding clarity but actually be adding something else, or you really <em>will</em> be adding clarity but <em>about the wrong thing</em>. Either way, the whole suffers. In software, this kind of misguided aim at clarity can lead to extra objects, APIs with too many parameters, and unhelpful type systems. Often the clarity comes in the wrong layer or at the wrong level: <a href="an-argument-from-jimmy-koppel.html">this argument</a> is, again, relevant.</li>
<li>Suppose it's true that "it is rarely possible for a programmer to take an arbitrary class and derive a new, useful, and correct subtype from it, unless that subtype is of a very specific [intended] kind." What would follow from that? Compare Item 18 of <em>Effective Java</em>, where Bloch claims that "inheritance violates encapsulation" and famously advocates for composition over inheritance.</li>
<li>Alexander and his group once gathered 390 requirements for "what ought to be happening near" a ticket booth. I have never worked on a project where the requirements were not much more extensive than my intuition initially suggested. It's safe to assume there are more requirements than you think there are. (Relevant: <a href="https://web.eecs.utk.edu/~azh/blog/thisprojectwillonlytake.html">this case study</a> that recently made the rounds.)</li>
</ol>

Reading notes: Patterns of Software

<h2>Reading notes: The Manager's Path</h2>
<p>On the one hand, <em>The Manager's Path</em> is pretty conventional: it reads like a business book and it's structured like a business book. On the other hand, the experience of reading it is totally unlike that of reading most other business books. Fournier is clearly writing from real experience and expertise, and--however thoroughly the book was edited after its first draft--its origins as a <a href="https://nanowrimo.org">Nanowrimo</a> project show in the book's urgency. (In the best way.)</p>
<p>I'm reminded of the poker world, where every so often an expert decides to transcribe a lot of their expertise in book form, usually without much regard for the traditional menu of literary forms. Fournier is a much more disciplined and skilled writer than most poker players, but I'd still put this in that category.</p>
<p>Miscellaneous notes:</p>
<ol>
<li>Fournier recommends budgeting 20% of a team's time for "generic sustaining engineering work." I take this as evidence for <a href="reading-notes-a-philosophy-of-software-design.html">my claim</a> that Ousterhout, if anything, shot too low when he suggested 10%-20% for (roughly) analogous purposes.</li>
<li>She notes that "a common dysfunction of technical teams is not shipping code." This is simple and profound. There are software-team-specific reasons for this, but most fundamentally, an underrated barrier to doing as much as possible is <em>not doing anything</em>. (See #6 <a href="on-productivity.html">here</a>.)</li>
<li>Here's a great sentence: "Think of process as risk management."</li>
<li>Here's a very good clause: "Code review is largely a socialization exercise..."</li>
</ol>
<p>Highly recommended, even if you aren't particularly interested in becoming a software manager.</p>

Reading notes: The Manager's Path

<h2>Software design</h2>
<p>One traditional division of software knowledge-–into algorithms, data structures, and system design-–leaves out software design: interfaces, object definition, dependency structure, and so on. So, for example, not <em>which database to use</em> but <em>how to use the database</em>. Here are some resources on the subject.</p>
<h3>To read</h3>
<ul>
<li>Jimmy Koppel's <a href="https://www.pathsensitive.com/2018/01/the-three-levels-of-software-why-code.html">essay on the three levels of software</a>. If true, this has deep consequences for how we think about creating, describing, and testing code.</li>
<li>Here is <a href="https://corecursive.com/036-jimmy-koppel-advanced-software-design/">Adam Gordon Bell interviewing Jimmy Koppel</a>. I loved listening to this, and review it periodically as a way to shake up my thinking and come back focused on more important things.</li>
<li><a href="https://www.amazon.com/Philosophy-Software-Design-John-Ousterhout-ebook/dp/B07N1XLQ7D/">A Philosophy of Software Design</a>, John Osterhout. This is best paired with <a href="https://www.pathsensitive.com/2018/10/book-review-philosophy-of-software.html">Jimmy Koppel's review</a>. I think Koppel basically has the best of it when they disagree, but even if (if!) there are some basic conceptual mistakes floating around, Osterhout explains too much, too clearly, with too many useful examples, for a serious student to ignore this book.</li>
<li><a href="https://www.amazon.com/Architecture-Patterns-Python-Domain-Driven-Microservices/dp/1492052205">Architecture Patterns in Python</a>, Percival and Gregory. The authors describe the creation of a full (not quite production-ready, but much more than a toy example) system, pausing to explain repositories, units of work, and much more. I marvel at how much widely applicable information they fit into a medium-length book.</li>
<li><a href="https://www.amazon.com/Working-Effectively-Legacy-Michael-Feathers/dp/0131177052">Working Effectively with Legacy Code</a>, Feathers. This is my single favorite software engineering book. One big reason it's relevant here--despite its being primarily a book about fixing, rather than designing, code--is because it's full of wonderful information about interfaces. (Also dependencies, responsibilities, and much more.)</li>
<li>Jonathan Locke's <a href="https://www.amazon.com/gp/product/B0042X99SA/">Coding: On Software Design Process</a> is a short, lovely book, roughly half of which is a series of arguments for and about thinking in terms of "micro-architectures." I'm not completely convinced, but I'm glad to have the notion of a micro-architecture in my toolbox. I'd love it if more programmers wrote this sort of novella-length manifesto.</li>
</ul>
<h3>...And an exercise:</h3>
<p>Sketch out the dependency graph for some fragment of your code base. Do this at both the "logical level" and the "code level" (as Koppel would put it), and don't conflate the two. Don't dismiss this as an elementary exercise: (i) it's rare to see it actually done (as usual, people rarely "do the reading") and (ii) I've never regretted taking the time to do it. Be careful not to conflate data flow with the direction of a dependency. (Ousterhout warns us against "temporal decomposition," and I've found both the phrase and the warning useful.)</p>

Software design

<h2>Software FAQ</h2>
<p>And by "frequently" I mean either (1) asked of me enough that I'm creating a stable public reference for it or (2) not asked of me very often, but I think more people should be asking it.</p>
<h4>Should I attend a bootcamp?</h4>
<p>Bootcamps are largely useful as a commitment device. A good portfolio project has as much signaling value as a bootcamp--much of the job-market value of the bootcamp simply is whatever project or portfolio piece you create in it--and needn't carry the negative signal a bootcamp can (pegging you as very junior).</p>
<p>So: maybe, depending on how you work best, but almost certainly not if the bootcamp isn't a very good one.</p>
<h4>What book should I read to learn programming?</h4>
<p>You probably shouldn't base your learning around a book. It's more effective to pick a project (initially something very small) and try to see it through, doing Web searches for help along the way. If you need some other sort of structure around your learning, a good MOOC relevant to your interests (search "MIT OpenCourseWare" on YouTube) is a good option.</p>
<h4>I want to learn fundamental algorithms and data structures. What should I study?</h4>
<p>Tim Roughgarden's MOOC (lectures available on YouTube) is a good place to start. MIT OCW (also largely available on YouTube) is usually my first YouTube search to learn about or brush up on some particular CS topic. I find it handy to have <a href="https://en.wikipedia.org/wiki/Introduction_to_Algorithms">CLRS</a> around, and <a href="https://www.algorist.com/">Skiena's book</a> is a nice complement to it. But you don't need any books.</p>
<h4>How did you get into programming? How did you get your first job?</h4>
<p>See <a href="how-i-got-into-programming.html">here</a>.</p>