Library

Cataloguing ideas about how to write software

  • What Software Engineers Need in 2026
    Agents are really good at telling you yeah, we can do that.... But humans are the ones that decide we should do that, and this is the skill of judgement. Wayne [Allen] said something that has really stuck with me: "Build the right thing before you build the thing right."
    Being able to visualize all over your code base how the different pieces are put together, how they communicate, how those things are tested. You are the architect: it is your job to validate that outcomes match intent.
  • Does Code Quality Still Matter? It Depends on This | AI Engineer
    All modifications to a system carry two categories of risk. 1) The probability of introducing a problem. 2) Making it more likely to have future problems.
    AI is making a new kind of software common: disposable software, with low consequences, few dependents and near-zero cost to replace or maintain. ... Durable systems will continue to be the most important systems in the world. But the most numerous systems will be disposable. ... In the future, we will apply engineering rigor the degree of disposability of the software.
  • Designing Data-Intensive Applications, 2nd Edition
    • How Important Is Reliability?
      As another example of how unreliable software can harm people, consider the Post Office Horizon scandal. Between 1999 and 2019, hundreds of people managing Post Office branches in Britain were convicted of theft or fraud because the accounting software showed a shortfall in their accounts. Eventually it became clear that many of these shortfalls were due to bugs in the software, resulting in many of these convictions being overturned. What led to this, probably the largest miscarriage of justice in British history, is an assumption by English law that computers operate correctly (and hence, evidence produced by computers is reliable) unless evidence exists to the contrary. Software engineers may laugh at the idea that software could ever be bug-free, but this is little solace to the people who were wrongfully imprisoned, declared bankruptcy, or even committed suicide as a result of a wrongful conviction due to an unreliable computer system.
    • The Meaning of ACID
      The safety guarantees provided by transactions are often described by the well-known acronym ACID, which stands for atomicity, consistency, isolation, and durability. The term was coined in 1983 by Theo HĂ€rder and Andreas Reuter, in an effort to establish precise terminology for fault-tolerance mechanisms in databases. In practice, however, one database’s implementation of ACID does not equal another’s. For example, as we shall see, there is a lot of ambiguity around the meaning of isolation. The high-level idea is sound, but the devil is in the details. Today, when a system claims to be “ACID compliant,” it’s unclear what guarantees you can actually expect. “ACID” has unfortunately become mostly a marketing term.
  • Splitting a Domain Across Multiple Bounded Contexts
    Bounded Contexts may or may not align with app or service boundaries. Similarly, they may or may not align with domain boundaries. Domains live in the problem space. They are how an organisation perceives its areas of activity and expertise. Bounded Contexts are part of the solution space; they are deliberate design choices. As a systems designer, you choose these boundaries to manage the understandability of the system, by using different models to solve different aspects of the domain.
    1. Bounded Contexts shouldn’t serve the designer’s sensibilities and need for perfection, but enable business opportunities. 2. The Rate of Change Heuristic: Consider organising Bounded Contexts so they manage related concepts that change at the same pace.
  • Visual and Collaborative Modelling | DDD Europe 2020
    It is not the domain experts knowledge that goes to production, it is the assumption of the developers that goes to production. -- Alberto Brandolini
    That shallowness of knowledge produces software that does a basic job but lacks a deep connection to the domain expert's way of thinking. -- Eric Evans
  • LLMs reward expertise
    The most important skill in prompting is expertise in the domain you’re prompting for. A good illustration of this is Terence Tao’s conversation with ChatGPT about the recently-discovered counterexample to the Jacobian Conjecture. This is not the same ChatGPT I talk to! I couldn’t get to where Tao gets, even with unlimited tokens to burn. ... If you have no domain knowledge, you can cling onto the LLM to at least get something. That’s not bad! But if you have domain knowledge, you can wring far more value out of the same LLM by steering it hard in the direction you want. Most of us will have to do a mix of both these approaches, since we have domain knowledge in some areas but not others.
    For many tasks, the human is the bottleneck, not the model, because the difficult part is in communicating to the model exactly what kind of solution the human wants. The information is “in the model” already, but it takes a very smart human to pull it out.
  • A good scrap: Disagreements can be unpleasant, even offensive, but they are vital to human reason. Without them we remain in the dark
    No truth is without some mixture of error, and no error so false but that it possesses no element of truth. If a man is in too big a hurry to give up an error, he is liable to give up some truth with it, and in accepting the arguments of the other man he is sure to get some errors with it. Honest argument is merely a process of mutually picking the beams and motes out of each other’s eyes so both can see clearly
 -- Wilbur Wright
    looked at through the interactionist lens, confirmation bias is actually a feature, not a bug of human cognition. It maximises the contribution that each individual makes to a group, by motivating them to generate new information and new arguments.
    It’s also possible to create these conducive conditions ourselves .... The first condition, of course, is to openly disagree. The members of the group must bring their own opinions and insights to the table, rather than just adopting those of whomever they like the most or nodding along with the dominant voices in the room. ... A second condition is that the debate should be allowed to become passionate without becoming a shouting match. ... a vital ingredient [is] ... good listening .... Third, the members of the group must share a common goal
  • The lethal trifecta for AI agents: private data, untrusted content, and external communication
    The lethal trifecta of capabilities is: (1) Access to your private data—one of the most common purposes of tools in the first place! (2) Exposure to untrusted content—any mechanism by which text (or images) controlled by a malicious attacker could become available to your LLM. (3) The ability to externally communicate in a way that could be used to steal your data (I often call this “exfiltration” but I’m not confident that term is widely understood.) If your agent combines these three features, an attacker can easily trick it into accessing your private data and sending it to that attacker.
  • LLMs’ Data-Control Path Insecurity
    This general problem of mixing data with commands is at the root of many of our computer security vulnerabilities. In a buffer overflow attack, an attacker sends a data string so long that it turns into computer commands. In an SQL injection attack, malicious code is mixed in with database entries. And so on and so on. As long as an attacker can force a computer to mistake data for instructions, it’s vulnerable.
  • Complexity and Modularity: Two Sides of the Same Coin | Tech Excellence 2024
    The goal of modularity is to minimize the cognitive load that is needed to evolve the system in the future
  • Functional C#: Handling failures, input errors
  • Cohesion and Coupling: the difference
    In essence, high cohesion means keeping parts of a code base that are related to each other in a single place. Low coupling, at the same time, is about separating unrelated parts of the code base as much as possible. In theory, the guideline looks pretty simple. In practice, however, you need to dive into the domain model of your software deep enough to understand which parts of your code base are actually related. It means that unlike such metrics as cyclomatic complexity, the degree to which your code is high cohesive and low coupled cannot be measured directly. It strongly depends on the semantics of the code which itself is an attribute of the domain model.
  • Decisions, Assumptions, and Overfitting or why most “clever” code ain’t so clever after all
    It is worth noting here that while some design principles (information hiding, DRY, etc.) are trying to at least localize decisions, the distinction between decision and assumption is rarely mentioned in software engineering. Still assumptions (and even more so pervasive assumptions) are even more critical, and in fact I’m currently leaning toward the idea that keeping track of your assumptions is even more important than tracking your decisions.
    In fact, a lot of people mistakenly assume that by building a (long) composition chain out of small, reusable, uniform, domain-independent functions they’re getting loosely coupled code. That’s wrong. As we have seen before, while the parts (taken alone) are loosely coupled, their specific composition may end up being extremely rigid under change.
    For real-world programmers, the most interesting properties often revolve around ease of change. ... A major factor in this “clever brittleness” is the common overfitting of such code to implicit assumptions hidden into the problem statement, exploited to make the code clever and directly contributing to brittleness under simple, realistic change requests.
  • The Bitter Lesson

    via https://tidyfirst.substack.com/p/taming-the-genie-like-kent-beck

    The biggest lesson that can be read from 70 years of AI research is that general methods that leverage computation are ultimately the most effective, and by a large margin. ... And the human-knowledge approach tends to complicate methods in ways that make them less suited to taking advantage of general methods leveraging computation.
  • Guidelines for Respectful Use of AI
    Don’t ask someone to read/review what you haven’t read or reviewed yourself. Shorter is better. AI is not an excuse to turn off your brain, or your heart.
  • Test Desiderata 2.0
  • Mob Programming: A Whole Team Approach | GOTO 2017
    When we study together, we build relationships that we can't build when we work together. Dedicated team learning time, such as Katas.
    Make retrospectives effective - do them more frequently - every end of day for 5 minutes: "what went well? turn up the good"
    If you go directly to trying to do the work that you think needs to get done, you lose the chance of becoming prepared to do the work well.
  • More Testable Code with Hexagonal Architecture | PhillyXP
  • Promiscuous Pairing - What Really Makes Pairing Work | Craft Conf 2023
  • Simple Made Easy | Strange Loop
    Simple means one role, one task, one concept, one dimension. Simple is not a count, does not mean “one instance” or “one operation”. What matters for simplicity is that there is no interleaving, not that there is only one thing. Simplicity is an objective notion. Easy means “near, at hand” such as on our hard drive, in our tool set, IDE, package manager. The second notion of nearness is “near to our understanding/skill set; familiar”. The third aspect of being easy is “near to our capabilities”. Easy is relative.
    We can only hope to make reliable those things we can understand. We can only consider a few things at a time. Intertwined things must be considered together. Complexity undermines understanding.
    Some things are Easy yet Complex. Simpler solutions increase flexibility. As we make things simpler, we get more independence of decisions because they aren’t interleaved.
    You can write modules with all kinds of interconnections between them. They might not call each other. It has nothing to do with the fact that there are two things; it has to do with what those two things are allowed to think about. Partitioning and stratification don’t imply simplicity, but are enabled by it. Don’t be fooled by code organization.
    When you simplify things, you often end up with more things. Simplicity is not about counting. I would rather have more things hanging nice, straight down, not twisted together, than just a couple of things tied in a knot.
  • The Building Blocks of Modularity | Mountainwest Rubyconf 2009
  • On the Criteria To Be Used in Decomposing Systems into Modules
    The benefits expected of modular programming are: (1) managerial--development time should be shortened because separate groups would work on each module with little need for communication: (2) product flexibility - it should be possible to make drastic changes to one module without a need to change others; (3) comprehensibility-it should be possible to study the system one module at a time. The whole system can therefore be better designed because it is better understood.
    In this context "module" is considered to be a responsibility assignment rather than a sub-program. The modularizations include the design decisions which must be made before the work on independent modules can begin.
    In the first decomposition the criterion used was to make each major step in the processing a module. One might say that to get the first decomposition one makes a flowchart. This is the most common approach to decomposition or modularization. It is an outgrowth of all programmer training which teaches us that we should begin with a rough flowchart and move from there to a detailed implementation. The flowchart was a useful abstraction for systems with on the order of 5,000-10,000 instructions, but as we move beyond that it does not appear to be sufficient; something additional is needed. The second decomposition was made using 'information hiding" as a criterion. The modules no longer correspond to steps in the processing. 
 Every module in the second decomposition is characterized by its knowledge of a design decision which it hides from all others. Its interface or definition was chosen to reveal as little as possible about its inner workings.
  • The Innovation of Cumulative Cultures and Developer Problem-Solving | Virtual Domain-Driven Design
    We are good imitative learners
    We really trick ourselves that we are learning a lot by passively consuming. You can get the feeling of learning, of progress. I try to limit my passive consumption and increase my active learning. I think of it like mindful engagement.
  • TDD Revisited | NDC London 2021
  • Structure and Interpretation of Test Cases | GOTO 2022
  • Intentional Code - Minimalism in a World of Dogmatic Design | Copenhagen DevFest

    good code is Code that is easy for someone with minimal domain context to read Code that focuses on developer-experience, debuggability, and usability Code where the intent takes up more visual space than the language syntax

  • How to Read Complex Code | YOW! 2021

    Reading code is its own skill, separate from writing it.

  • Beck Design Goals (four rules of simple design)
    Passes the tests, Reveals intention, No duplication, Fewest elements
    At the time there was a lot of “design is subjective”, “design is a matter of taste” bullshit going around. I disagreed. There are better and worse designs. These criteria aren’t perfect, but they serve to sort out some of the obvious crap and (importantly) you can evaluate them right now. The real criteria for quality of design, “minimizes cost (including the cost of delay) and maximizes benefit over the lifetime of the software,” can only be evaluated post hoc, and even then any evaluation will be subject to a large bag full of cognitive biases. The four rules are generally predictive. -- Kent Beck
    The “no duplication” is perhaps the most powerfully subtle of these rules. It's a notion expressed elsewhere as DRY or SPOT. Kent expressed it as saying everything should be said “Once and only Once.” Many programmers have observed that the exercise of eliminating duplication is a powerful way to drive out good designs.
  • Refactoring: Improving the Design of Existing Code (2nd Ed)
    • Extract Function: Motivation
      During my career, I’ve heard many arguments about when to enclose code in its own function. Some of these guidelines were based on length: Functions should be no larger than fit on a screen. Some were based on reuse: Any code used more than once should be put in its own function, but code only used once should be left inline. The argument that makes most sense to me, however, is the separation between intention and implementation. If you have to spend effort looking at a fragment of code and figuring out what it’s doing, then you should extract it into a function and name the function after the “what.” ... The fact that size isn’t important was brought home to me by an example that Kent Beck showed me from the original Smalltalk system. Smalltalk in those days ran on black-and-white systems. If you wanted to highlight some text or graphics, you would reverse the video. Smalltalk's graphics class had a method for this called highlight, whose implementation was just a call to the method reverse. The name of the method was longer than its implementation—but that didn’t matter because there was a big distance between the intention of the code and its implementation.
    • Refactoring, Architecture, and YAGNI
      The real impact of refactoring on architecture is in how it can be used to form a well-designed code base that can respond gracefully to changing needs. ... Instead of speculating on what flexibility I will need in the future and what mechanisms will best enable that, I build software that solves only the currently understood needs, but I make this software excellently designed for those needs. As my understanding of the users’ needs changes, I use refactoring to adapt the architecture to those new demands. I can happily include mechanisms that don’t increase complexity (such as small, well-named functions) but any flexibility that complicates the software has to prove itself before I include it.
    • Good code should be obvious
      
 programmers love to argue about what good code looks like. I know some people object to my preference for small, well-named functions. If we consider this to be a matter of aesthetics, where nothing is either good or bad but thinking makes it so, we lack any guide but personal taste. I believe, however, that we can go beyond taste and say that the true test of good code is how easy it is to change it. Code should be obvious: When someone needs to make a change, they should be able to find the code to be changed easily and to make the change quickly without introducing any errors.
  • A Daily Practice of Empirical Software Design | DDD Europe 2023
    Two elements of code are coupled with respect to a specific change if making the change in the first element means that the second element also has to change.
  • Code Smells - Developing Design Sense for your Code | Agile Latvia
  • E42: The offloaded brain, part 2: applications
    Perceptions aren’t built up from fundamental values like length or weight. It’s more that we grasp complex, relevant information instantly, as a whole. It’s not often particularly useful to put in the effort to decompose that whole into its smaller parts. ... I want to claim programmers learn to perceive bad code in a learning process that is, for practical purposes, the same as babies learning to recognize faces or veterinarians learning to recognize dull cows. Code smell detection is possibly built on top of our visual system’s innate ability to attend to symmetry, density, or other patterns. ... Be more aesthetic, keeping in mind that the point is to *expand* your aesthetic perceptions, not just to reiterate prepackaged and value-laden perceptions like “elegance” and “simplicity.” ... Just reading code, or reading definitions of code smells, isn’t sufficient for learning.
  • Making is Easy, Mending is a Challenge | Maintainable Software Podcast
    The cost of software is in the reading. You write it once, people read it for years. When people write software for their readers, with good names, with organization that is gentle on someone who hasn't looked at the software before. ... [Gentle] is writing the software for them, not for us. The desire to be seen to be smart and clever is probably is a thing we should resist. I love writing clever code, but I've written code that I, the author, could not understand later. And that means that no one can understand it, if the writer can't understand it.
    Here's a continuum. ... You have to put yourself on one extreme category or the other. On one end is, "I change existing code for a living" and on the other end is "I always write new code". Almost 100% of the people, if forced to choose one of those extreme two categories, they have to put themselves in "I change existing code for a living". We all like to think that we write new code, but we really don't. We change code for a living. If it's true, that we change code for a living, then it's really important that code be readable.
    If you can tell who wrote the code, it's costing you money every time you look at it.
  • DDD: Strategic Design | JAOO
  • DevArch: Software Architecture for Developers | Build Stuff
  • AI Talks: Augmented Coding: Mapping the Uncharted Territory | Calgary Software Crafters
  • Stop Over-Engineering | Build Stuff 2016 Opening Keynote

    Use cost benefit analysis (freq of failures * costPerFailure / investment). Prioritize the high value use cases. Don't write expensive code handling edge cases that almost never happen if you can detect when you have left the happy path and let a human address it.

  • What I've learned about DDD since the book | QCon London 2009
  • Workflows of Refactoring | OOP 2014 Munich

    Introduction to what refactoring is and when to do it