DEV Community: KW Stannard

Avoiding nil errors

KW Stannard — Fri, 16 May 2025 01:06:37 +0000

Here is a quick way to avoid nil errors and get better failures in Ruby and Ruby on Rails. Convert hashes with known keys into Structs:

data = { a: 1, b: 2, c: 3}
...
MyData = Struct.new(:a,:b,:c)
data = MyData.new(a: 1, b: 2, c: 3)

Structs will throw if you introduce a typo instead of returning nil. This tightens your feedback loops and reduces debugging time.

hash[:d] => nil
struct[:d] => in 'Struct#[]': no member 'd' in struct (NameError)

That is cool. What about in more fluid situations like user input? You can convert arbitrary incoming hashes into known structs quickly with the following:

params = {a: 1, b: 2, c: 3, x: 9, z: 0}
MyData.new(**params.slice(*MyData.members))

Pitfalls

While Structs have much the same interface as hashes, there are some tricky differences.

Hash#each is equivalent to Struct#each_pair.
Hash#keys is equivalent to Struct#members.
There is no equivalent to Hash#fetch.

Tridactyl and the death of tabs

KW Stannard — Mon, 21 Apr 2025 14:50:00 +0000

This is a simple personal workflow explanation.

The average number of tabs I keep open is 4. The other day I accidentally closed the last tab and thus the Firefox window. I even hide all Firefox GUI elements so that the page takes the whole window. Yet, I never feel at a loss for how to find a page that I need. The secret is Tridactyl.

Tridactyl is a Firefox plugin that injects keyboard shortcuts on each page, which is why I started using it. I no longer needed to use the mouse on 99% of web pages that I visit. I still had dozens of tabs though.

I eventually noticed that the open and tabopen commands showed a list of websites based on the arguments that are being passed. What is happening here is that Tridactyl is taking your history and your bookmarks, concatenating them, and running a search on that list for any websites that match the arguments.

For example, ":open dockerfile args" will search that list for anything that matches "dockerfile" and "args". I usually get a list with a few items including the direct link to the "args" section of the dockerfile documentation. Very helpful.

From there it is just a matter of habit of closing tabs the moment you realize you don't need them anymore and then utilizing Tridactyl's history search when you later need something again.

Software Calcification

KW Stannard — Wed, 16 Apr 2025 17:38:37 +0000

Calcification: the gradual, almost imperceptible transformation of a soft, flexible body into a hard, brittle body.

Software: The original computers were 100% hardware. Inputs were given via wheels, knobs, and cards. Outputs were generated by gears, wheels, transistors, and tubes. The computer had one, maybe two functions it could run. Creation and change were extremely expensive. But, when general purpose computers were invented, you could create and edit functions by merely arranging bits. Thus, "software" was easy and pliable by comparison.

Software can calcify though. The bonds between parts of the software multiply and strengthen until movement ceases. Eventually, the software faces a stiff wind from an unexpected direction or heavy blow at the wrong place and crumbles, never to recover.

Sometimes a little calcification is even a good thing. We all have bones, don't we? You don't want your femur fusing to your hip though. Objects in OO can be thought of as planned calcification in a way. We accept that some functions are tied together somehow and that it makes sense that they would move as one.

How do you know your software is calcifying, even as a non-technical person? You start hearing more and more things like "We could do X, but then we need to change Y". Bugs are taking longer and longer to fix. Features are taking longer and longer to add. Engineers who used to be rising stars are mysteriously burning out and quitting despite no indication of your org being toxic.

Coupling

The main cause of calcification is a failure to keep coupling to a minimum. Engineering as a profession I think does not understand the threat of excess coupling. Plenty has been written about coupling, but because of the time that passes between when software is first written and when the pain starts getting felt, the coupling gets normalized within your engineering culture. "That function has always gone 5 methods deep into this object and it has never been a problem before." the engineers will say. "We have always used dozens of function mocks per test." they will say. Excessive coupling is normalized in your organization.

Excessive coupling can be caused by poor:

Domain Modeling

Another cause of calcification is bad or out of date domain modeling. Changes are hard because the system does not make sense. This one also tends to be difficult to discover and then the pain gets normalized. "All my design documents have 30 different models, most of which have names only comprehensible to me, and the arrows are going every which way. But, this has worked so far." your architects will say. No one will dare to make a change to something complicated and only barely works for your business.

Testing

Willingness to change, adapt, and move are all facilitated by a feeling of security and nothing makes an engineer feel more secure than a good suite of tests. Signs that your test suite is not up to par. "We need to run a full manual UAT program before every deployment" your engineers will say. "We re-run the test suite several times in case of flaking tests" you will hear.

Iteration duration

Most software engineering requires some number of loops. There is the micro-loops of Red-Green-Refactor. There is the bigger loop of commit-push-merge. There is the bigger loop still of build-and-release. Slow-downs in these make changes harder. They stiffen and calcify your thinking. When your build time increases, your engineers become less willing to agree to comments on PRs because it will trigger more builds and more waiting. Reviewers will rubber stamp the PR rather than risk getting stuck waiting 30 minutes for their changes to be completed and built. More coupling, bad domain modeling, and bad testing get introduced. The downward spiral of calcification intensifies.

Prevention

There is no silver bullet here. There are dozens of tools and skills. To name a few:

Test Driven Design

TDD is great, but a common pitfall is letting the code dictate the tests, rather than letting tests dictate the code. This is closely related to:

Minimal, well defined interfaces

Know your interfaces. Know the levels of your application. Are you running a web app? Your primary interface is http requests. Do you have a job queue? That is another interface. Do you have both a web app and a job queue using the same code? Then you have business logic interfaces as well. Lastly, object and function interfaces.

Utilize coherence to cut interface sizes down. If you are passing a ton of references or are reaching deep into a reference, there is probably poor coherence somewhere.

Stop using so many mocks please

Your tests are also part of the coupling. Every mock you make is increasing the coupling and causing calcification. For example: instead of writing a test that takes an http request, mocks out 50 things, and returns a result, write a test that takes an http request, mocks out any web requests to external services using something like WebMock, and returns a result. I promise you you will thank me when you realize the client library you were using is no longer maintained and you can swap it out without changing a line of tests.

Small refactorings

Little problems left to fester will often become very big problems given enough time. Normalize your engineers spending 5-15 minutes per day fixing little issues.

Reversion

I am sorry for you. You will need broad support to turn things around, but if you don’t have that you can do a few things that will might help convince others or at the least, convince youself.

fix small things

Pick a small subsystem or class and peck away at it. Reduce the public API from 5 functions to 4 functions. Fix a naming issue. Delete those pointless tests that someone wrote. Add a useful test.

Do this enough and you will make surprising headway over the course of your tenure. Do not let this spiral and take up your whole day. If the only thing you can think of is a big rewrite, you may want to go read the Refactoring book for ideas.

Conclusion

Thanks for reading. This is more of a rough draft on this concept, but hopefully it is helpful.

Naming is a bad place for laziness

KW Stannard — Wed, 16 Apr 2025 14:25:40 +0000

A very common problem I have seen in pretty much every code-base is lazy naming and it is costing you time and money every day.

What is lazy naming?

Lazy naming is a form of tech debt. It is the author throwing up their hands and saying "I don't really understand why I am making this code, so in order to complete the task I will give it a meaningless or generic name". This causes issues for everyone else as the name does not help the team with understanding and encourages other people to accept poor naming. This is a cause of application calcification.

Lets look at a couple types of lazy naming.

Grab-bag names

A grab-bag is a pile of mostly unrelated code. Sometimes those methods cannot even function on their without importing other code. Perhaps the author was tasked to move everything out of a big file and ran out of time so they created a grab-bag for all the stuff they didn't get to. Perhaps the author ran out of steam and wanted to get back to it later but it is still there a decade later.

An example here is ActiveRecord::Core. What is a Core? Who knows. What goes in a Core? Anything. Core is a module with a grab bag of methods that should be in other modules. This causes everyone to jump between files to follow code flows and complete tasks. You cannot use Core without every other ActiveRecord module. You also cannot use other ActiveRecord modules without Core. So, really, the extraction of ActiveRecord::Base into modules did nothing.

Solution: move what you can to other modules and what you cannot into the root class. Coherence is the name of the game here. If you cannot use a module outside its original context, then there was no point in making the module.

ThingDoer names

These are names where there is a clear purpose to the code contained within, but the author failed to use the name to inform future readers as to what to expect inside. This can accellerate purpose drift and feature creep.

Some common ThingDoer names: ThingProcessor, ThingHandler, ThingFunction.

Solution: Take a minute to try to describe the code in a few words. Perhaps your SaleProcessor could be a SaleDocumentIngestor. Perhaps your UsernamePasswordHandler could be UserAuthenticator.

Conclusion

Proper naming is key to ensuring that your application can continue to grow and change. Take the time to do it right.

Development as a warehouse

KW Stannard — Mon, 14 Apr 2025 15:32:01 +0000

Analogy time.

Software and system design are difficult to comprehend without a framework. Analogies can help clarify things. So, in order to help, lets analogize your application as a warehouse and features are boxes that business wants to put in your warehouse. As a software developer, your job is to help manage the warehouse.

Now, as a new warehouse manager, you start with an empty warehouse/application. You want to get to market as soon as possible. Unfortunately, you have never seen or heard of a warehouse before, so you pick up a box, walk two feet in the door to the warehouse, and place it down. You get another box, walk two feet in the door, and place it down. Another box, you put it on top of the first two.

Soon you are creating pyramids of boxes. Mazes of boxes. You feel like a genius when you put a new box in. Your boss is amazed and makes you chief warehouse executive.

But, soon you cannot keep up with the demand. Some boxes are buried in the wrong places. Some boxes are starting to mold. The owners have hire a small army of assistant box management people but the maze of boxes is incomprehensible to anyone but you. The warehouse is losing money hand over fist and eventually is sold for pennies on the dollar to StoringSpoons who fires everyone and collects the money as the warehouse crumbles into dust.

How can you, the fresh and intrepid warehouse manager, stop this grim future? Warehouses have learned how to scale to massive sizes and with a few practiced tools in your belt you can too.

Extension

This is kind of like having a roller line.

  ┌─────────┐                  ┌───────────┐   
  │         │                  │           │   
  │         │    ┌────────┐    │           │    
  │         │    │        │    │           │   
  └─────────┘    └────────┘    └───────────┘   
ooooooooooooooooooooooooooooooooooooooooooooooo

New boxes are added to the front of the line and all the existing boxes roll down the line. The line is "open to extension". If you want to remove a box, you pull it off the line and that does not affect adding more boxes to the line.

Example of extension: Lists are lines of items. If you can reduce your concept to a list of things, it is probably extension.

Encapsulation

  ┌─────────┐  ┌─────────┐
  │ ┌┐┌────┐│  │         │
  │ └┘│    ││=>│         │
  │   └────┘│  │         │
  └─────────┘  └─────────┘

Boxing. You need to send out manuals, dials, motors, cases, and basins to the customers. You could have them all individually and have 5 work items, or you encapsulate them in a box labeled "washing machine kit" and have one item.

Example: Files. Files are really just thousands, millions, or billions of bits in memory, but if you encapsulate those bits into a "file" with a set of functions to perform tasks on those bits, then it becomes easier to think about than needing to handle those bits yourself.

Composition

A type of encapsulation and alternative to inheritance. The washing machine kit box "has a" dial. The dial is put into the box.

Example: Directories "have many" files as a way to organize and think about the files. One can move all the files in a directory with one command instead of many commands. Just like one can move the contents of a box by moving the box.

Inheritance

A way to group objects by shared attributes and functionality. You as the warehouse manager might need to store large things and small things so you make two bins for empty boxes. "Big", and "Small". As time goes on you may subdivide this further, but do note that you probably need to throw away the old groupings to prevent confusion as the groupings are conceptually linked.

Example: Executable files are a subtype of files. They also are a collection of bits and can be manipulated the same as all files.

Dependency Injection

You hire your first employee, Devin. You start writing down what needs to happen at the warehouse. "Devin preps 30 boxes." "Devin fills 30 boxes." etc. One day, Devin quits and you hire Billy. Oops, now you need to change everything. Instead, you could have written "Box prepper preps 30 boxes" and "box filler fills 30 boxes" then given Devin the titles of Box prepper and Box filler.

Example of dependency injection: arguments to your executable are you injecting dependencies. You don't write a custom file mover for every file in the system. You pass the file to the mv function.

Conclusion

These are all tools that need practice and exercise. No one builds a perfect warehouse the first time around, much as no one builds a perfect application. The goal is that when you discover why the application is wrong, that you can quickly fix the problem. This might be more of a series as I think of more patterns that can be like a warehouse.

How to manage developers

KW Stannard — Tue, 14 May 2024 17:47:06 +0000

Hey you!

Me?

Yeah, we need you down here.

Why?

We need to see how fast you can walk.

Uh, ok. Let me come down.

Thanks. Can you please walk from here to that cone.

Sure thing.

Alright, you can walk about 3 miles per hour.

Why did you need to know that?

I need to tell the board how long it will take you to get to Chicago.

But why are you measuring me walking?

Well, running will wear you out.

But, I am a goose, why aren't you measuring how fast I can fly?

We don't know how to measure flight. Now, get walking. we will see you in Chicago.

What is software development? (It’s management)

KW Stannard — Wed, 10 May 2023 13:28:43 +0000

A lot of people have expended a lot of words asking what software development is metaphorically. Are we construction workers? Are we factory workers? Are we gardeners? Are we architects? Lets look at what we know.

Where is the value in software? The value that is produced is in the data that our users want to see on their machines. So, value == data + presentation.
What makes the value? The application provides data generation and presentation, so the application is ultimately the value generator.
What is the relationship between the software developer and the application? The software developer creates detailed instructions for the application on how to generate value, determines and monitors metrics to see how well the application is generating value, and makes decisions based on those things.

What does this mean? What other occupation does things like making metrics, monitoring them, and using them improving value production through things like documentation and instruction? There is an answer to this that should be immediately understandable to non-technical people. Software development is a type of management. The “workers” are the processes running on computers.

Imagine a factory that has all the management go on a retreat. The workers will continue to make product for some amount of time until a failure happens that is not accounted for previously. Perhaps no workers were informed of how to hire a technician to fix a critical machine.

The same is true in software. If a development team leaves one day, the application will continue to provide value until it fails in a way that was unaccounted for.

Why does this matter? For one thing, I think this has implications on how a business needs to grade software developers.

What would you grade a manager on and how would that map to software? I think the most obvious thing would be the application metrics. How many requests are getting served? How long does it take a user to get what they want?

What are we grading developers on now that do not make sense to grade managers on? Do we grade managers on how many instructions they give to workers? Is it a good idea to grade them on lines added to the employee handbook?

What else does this metaphor help with? Are there types of software development that don't fit into this metaphor?

An easy safety in git

KW Stannard — Tue, 03 May 2022 04:21:34 +0000

So, everyone's git right of passage is to nervously try to run a git command and then realize with horror that you just lost your work on your local repo. Then you run to google and try to find out how to reverse what you just did and run some archaic commands to find the lost commits.

With a small amount of foresight, you can just create a new branch called "backup" pointing to your work and reset back to it if necessary.

$ git branch -C backup
# mess up your git branch
$ git reset backup --hard
# good to go

Things that are controllers

KW Stannard — Fri, 25 Mar 2022 02:03:08 +0000

ActionControllers for the http interface.
Rake tasks are controllers for the cli interface.
Workers are controllers for the async job queue interface.

Just a random thing more people should know about.

Quadragonal

KW Stannard — Wed, 23 Mar 2022 13:51:31 +0000

Bob: My tests take so long!

Steve: Why do they take so long?

Bob: My records take forever to create and save to the database!

Steve: Why does your records taking forever affect your test run so much?

Bob: Because my logic is pulling and storing stuff in the database and I need to test it.

Steve: Why is your logic pulling and storing in the database?

Bob: uhhh... because that is how I learned how to write Rails? You aren't about to lecture me about Hexagonal are you?

Steve: No, but have you ever seen a fast test suite with the way people normally write Rails?

Bob: No, but I feel like you are about go on about something, so go ahead and get it over with.

Steve: So, the key to a fast test suite is to separate handling of logic from handling of state as much as possible. That is fairly easy in most cases. First, you extract the data from the database. Then, you run the logic on the data. Finally, you save the result to the database in a transaction. What does that get you?

Bob: I think I see, you don't have costly database dependencies within the business logic.

Steve: Yes, and the tests for the full unit only needs a success and failure case, because none of it matters unless the transaction runs and succeeds.

Bob: Thats all nice, but ActiveRecord has so many methods that can query the database, it is easy to get tripped up.

Steve: Yes, that is a tricky one. You may want to do something like disabling the connection. This for example prevents calling the database by switching to a non-existing connection specification.

class ApplicationRecord
  def self.with_no_connection!(&block)
    old_name = connection_specification_name
    self.connection_specification_name = 'with_no_connection active'
    yield
    self.connection_specification_name = old_name
  end
end

Bob: I could perhaps use that during testing but not in production so that I don't get 500s from test concerns.

class ApplicationRecord
  def self.with_no_connection(&block)
    if Rails.env.test?
      with_no_connection!(&block)
    else
      block.call
    end
  end
end

Steve: Good call.

Bob: To go over it one more time. We improve our testing speed by avoiding calls to the database within the logic. First extract all the needed data, then run the logic on the data, and finally save back to the database. Do you have a little example?

Steve: That sounds right. Here is an example in a controller:

class MovesController < ApplicationController
  def create
    # query db, build objects
    person = Person.include(:places).find(params[:id])
    old_place = person.current_place
    new_place = Place.find_by(params[:new_address])

    # pass objects to stateless logic
    ApplicationRecord.with_no_connection {
      Move.call(person, old_place, new_place)
    }

    # save state in transaction
    transaction do
      person.save!
      old_place.save!
      new_place.save!
    end

    head :no_content
  end
end

Bob: That looks pretty close to normal Rails, plus in the Move tests I do not need anything in the database! Interesting. What is with the title of this article anyways?

Steve: Quadragonal is a play on Hexagonal, but there are only 4 parts. The controller, the state, the logic, and the view.

Composition and Inheritance

KW Stannard — Fri, 25 Feb 2022 16:00:55 +0000

Content Warning: scatological example

I was discussing composition over inheritance with a friend recently and he sent me this as a way to help clarify the subject.

# Inheritance
class Animal
  def eat
    # eats
  end
end

class Dog < Animal
end

# Composition?
module Pooping
  def poop
    # poops
  end
end

class Cat
  include 'pooping'
end

# Composition?
class Farting
  def fart
    # farts
  end
end

class Hamster
  has_a :farting
end

So, first off, one extremely common misconception is that the second scenario is OO composition. It is not. Only the third example is OO composition because OO composition is an object containing references to other objects. However in the third example the name Farting is bad because Farting is a state of being and not an thing that can be encapsulated by a hamster. Names are important for clarity.

After reading this I decided to show him what OO composition might look like for the case of modeling animal digestion.

First off you need to consider the objects involved. An animal is obviously there. There is also a system of organs in an animal for digestion called the gastrointestinal (GI) tract. For simplicity sake I will avoid modeling the individual organs of the GI tract and move on to writing some code for eating.

class Animal
  def initialize
    @gi_tract = GITract.new
  end

  def eat(food)
    @gi_tract.injest(food)
  end
end

class GITract
  def initialize
    @contents = []
  end

  def injest(food)
    @contents << food
  end
end

Great, now we have an animal that eats and successfully passes the food to its GI tract. How about pooping?

class Animal
  ...
  def poop
    @gi_tract.evacuate
  end
end

class GITract
  ...
  def evacuate
    Waste.new(@contents.shift)
  end
end

That is nice, but not quite right. Usually irl I get told I need to go poop by my gi_tract. We need a two way relationship between the animal and gi_tract in order to model that.

class Animal
  def initialize
    @gi_tract = GITract.new(owner: self)
  end
  ...
end

class GITract
  def initialize(owner:)
    @owner = owner
    @contents = []
    @waste = []
  end

  def digest
    @contents << nil
    @waste << @contents.slice!(1..-5).compact.map{|food| Waste.new(food) }

    @owner.poop if @waste.any?
  end

  def evacuate
    @waste = []
  end
  ...
end

Okay, that is looking good. We have now modeled an Animal eating and pooping by having a GI tract. But, what about modeling subtypes of Animal? Here is where we can introduce inheritance back in as inheritance is for modeling subtypes. Lets use Cats and Hamsters because they eat different things and have different subtypes of GI tracts and cats have a different pooping behavior.

class Cat < Animal
  def initialize
    @gi_tract = CarnivoreGITract.new
  end

  def poop
    hide
    squat
    @gi_tract.evacuate
  end
end

class Hamster < Animal
  def initialize
    @gi_tract = HerbivoreGITract.new
  end
end

Great! Lets wrap this up. We have successfully encapsulated a lot of behavior inside of GI tract objects. By having that behavior encapsulated we can make changes with much more confidence and with fewer errors. We could from here fairly easily model a cat that is herbivorous or a carnivorous horse.

Leave comment on what you would do next!

Mixins are inheritance

KW Stannard — Fri, 31 Dec 2021 03:09:14 +0000

Inheritance is getting a bad rap and rightfully so in my opinion. Inheritance has turned out to be a specialist tool for specific situations and was unfortunately overused. Long story short, try composition before inheritance.

Now, that said, I have come across developers who understand the above and yet still fall unwittingly into the trap of inheritance over-use. This happens because they think mixins are composition, but mixins are actually Ruby's answer to multiple inheritance. Don't believe me?

Here is an example of classic inheritance:

class Superclass; def talk; "world"; end; end
class Subclass < Superclass; def talk; "hello #{super}"; end; end

Now here is an example usage and a look under the hood.

puts Subclass.new.talk
#> hello world
puts Subclass.ancestors.inspect
#> [Subclass, Superclass, Object, PP::ObjectMixin, Kernel, BasicObject]

Now, here is the same code using mixins. Note that the method signature is identical.

module Superclass; def talk; "world"; end; end
class Subclass; include Superclass; def talk; "hello #{super}"; end

And again, a usage and a look under the hood. Note that they are identical to the classic inheritance implementation.

puts Subclass.new.talk
#> hello world
puts Subclass.ancestors.inspect
#> [Subclass, Superclass, Object, PP::ObjectMixin, Kernel, BasicObject]

To sum up, mixins are going to run into most of the problems you would get with inheritance because they are a type of inheritance.