No Clever Code

Read this first

Don’t Mock It: Hack It

Python holds a deep, dark secret: it can be as unpredictable as Ruby if we let it. Even with the new typing1, the staggering flexibility of Python at runtime remains. We can change individual instances of classes to anything we want, and nothing can stop us

But It Would Be Wrong

The whole point of classes and instances is that they are predictable: every instance should act the same; every subclass should do the same things, perhaps in slightly different ways2. Cleverly3 changing instance 47 to get around some restrictive class design might feel good, but it is a land-mine you planted waiting for the next developer to come along


Except for testing. Testing less than end-to-end involves making some code think that it’s in the real world when it is not. Be it mocks,, stubs, composition, or references to services, tests need to simulate other code to simplify, isolate, and...

Continue reading →

The Magical, Full‑Stack Developer or The Intellectual Shmoo

Software, at least traditionally, was made in layers and parts, and each part has its own domain and its own technology. Developers know multiple languages and multiple domains, i.e. their skills gained from training and experience, but no developer knows every language and domain, however inconvenient this is for managers, and therefore recruiters. A team would have members who brought different skills and experiences.
A recent innovation is the invention of the Full‑Stack Developer to get exactly the skills needed in one engineer

“Stack” is a description of technologies that interact with each other. Originally, the stack extended down to the operating system and the binary network protocol and the physical electronic connections, and now the most common range of the stack is the data store (e.g. Redis, SQL) to servers (e.g. APIs) using communications protocols (e.g. REST, Thrift...

Continue reading →

The Futures of Python

Futures defer execution of code. They can allow code to wait for external resources like file reads, network calls, and database access, and then automatically continue without stopping every other operation. They allow the definition (i.e. coding) of entire sequences of work in one place rather than having one function hand-off to another (presumably coordinated) function

Python’s syntax for Futures (and coroutines) is simple and, for me, surprisingly confusing at first. I have concluded that Futures in Python boil down to three (3) rules:

  1. Functions prefixed with async return a Future1 when called even if the function itself does not return a result. The code inside the function does not execute until something resolves the Future

  2. The ways to resolve a Future are

    • await <Future>
    • asyncio.get_event_loop().run_until_complete(<Future>) or<Future>)2
  3. Use await inside asyn...

Continue reading →

Don’t Mansplain Your Code

When getting one’s code or wiki entry or blog post reviewed, if a reviewer asks a good question (e.g. what the code is doing or why the code does not follow the common conventions), don’t answer them directly The problem is not that they have a question; the problem is that your code or text is not clear

Don’t mansplain with comments, READMEs, or call-outs in documentation; improve it so it can clearly speak for itself. A comment can improve code if it explains why the code is not doing the obvious thing; otherwise, it is compensating for something that will, once improved, not need compensation

Comment only what the code cannot say – Kevlin Henney

Change the text or code so it is clearer: improve the nomenclature or break operations into separate functions; add a diagram to show what you mean; replace magic numbers and codes with constants. You will likely find bugs, missing cases...

Continue reading →

The Tragedy of Heroes

In times of crisis, everyone just gets stuff done to keep the boat afloat and ship that one, promised feature. Young startups are constantly in crisis: pivoting, shucking and jiving, all hands on deck, working all night to get the demo up. They need heroes who can do anything and everything. They don’t have time to explain or document, and — since everything is changing anyway — “what’s the point?”

Some people thrive in a chaotic environment. It engages their complete concentration and creativity. They are praised and rewarded for how much they can do and, often, how much effort they put into doing it. They know where things break, what they look like when they break, and how to fix them (at least in the short term). They like the environment; it fits them, it finds them, it breeds them. They are heroes

A startup entering adolescence has these heroic veterans of the early battles. As...

Continue reading →

Source Code as Poetic

source code,
like poetry,
is more than its words and symbols
(or the bytes they represent)

it has shapes that communicate
its intentions

While we might share Mr. Jourdain’s1 delight, we should not ignore the shape of our code as well as its syntax. In deciphering code, others (or ourselves after a few weeks) can use the shape and flavour of code not merely as artistic or affected expressions, but as guides to its meaning. While rhyming, alliteration, and meter are usually not practical for source code itself, patterns, rhythms, and flow are

Patterns and rhythm are how the logical parts of code (e.g. functions) resemble each other, how they appear when arranged or nested (e.g. methods in a class), and how variations from these patterns are intentional and recognizable. Top-level code, often the public-interface functions2 that begin the orchestration of all the specialized procedures...

Continue reading →

Four Unintuitive, Critical Things to Learn About SketchUp

1. It Really Wants To Be Modal

click-release-move instead of click-drag1

The common click-drag idiom used everywhere else does not work well in SketchUp

Once you are in a mode (by selecting a tool and clicking on a starting point once), you can rotate and pan the view (camera) to find and select the points you want to synchronize with your clicked-point or enter a numeric length. Then, exit the mode by clicking once or pressing Enter for the number. Holding the left mouse button makes it harder and prevents some nice features (see Control the Axes below)

2. Use the Tape Measure and Guide-Lines Constantly

Guide-lines allow you to do what you want without fighting the model. If you want to show a dimension and you cannot find the points to connect, draw a guide exactly where you want (e.g. specify a length) and use the endpoints of the guide for your dimension2
When resizing or...

Continue reading →

Temba, His Arms open()

Languages have rules about how their words or signs fit together (syntax). They have patterns of how their words or signs tend to sound or look, how some elements are built out of others, and how poets break the rules to make things interesting. One can have words or signs that look like they belong to a language, are sequenced, conjugated, declined, and capitalized correctly, and yet are not valid examples of that language. Likewise, one can have elements of a language used correctly according to those rules, but their combination has no meaning1 according to its semantics, even to poets2

Software .. [are] systems of meaning – Kevlin Henny

Software languages, while using words from human languages, are even more rigid in their grammar, syntax, and context, and still are able to hide incorrect meaning in technically correct text

This And That

Even seemingly obvious things like...

Continue reading →

Professionalism ∝ Passion-¹

In the 1990s, we were all searching for passion. Passion leads to Excellence, and we were all in search of that. In the 2000s, geeks took over, and geeks are just people who show their passion. The passionate, geeky software developer is a cliché, albeit a common reality. Many businesses and thought-leaders welcome that passion, and even try and motivate it

They enjoy the benefits of the drive and attention passion incites in software developers. They love the passion-fired momentum geeks have for “their” features. Build and support engineers can get passionate about their parts in a process even if customers never see it. But businesses also call on a different aspect of their workers from time to time: their professionalism

Compare the meanings of professional and its antonym amateur: the latter term might mean less-skilled (than a professional) or a dilettante. but originally it...

Continue reading →

Technical Debt Is Cholera, not Quicksand

Technical debt (TD) – the compromises we make to get stuff out the door – is more often acknowledged and occasionally quantified. We categorize the inefficiency and difficulty working with it—the “interest” on the debt—as an unfortunate cost. Fixing technical debt (paying down the “principle”) competes for resources with new development and tangible defects

The common TD horror story is changing the behaviour of badly-coded modules1. For example, spending hours adding a simple variation to an existing implementation, which has never worked consistently (and never been fully tested – let alone built for extension or reuse), is dangerous as well as frustrating. Without tests or clear documentation, we are never sure what good behaviour is, so extending that behaviour is often an exercise in faith2

In analyzing technical debt, we tend to mythologize it:

  • Technical debt is something...

Continue reading →