Reinhardt.io

Leveraging Documentation for AI Tools

Thu, 02 Oct 2025 15:29:00 +0000

Memories of the past prepare us for the future. If every day we had to re-learn how to tie our shoes, brush our teeth, walk, and a million other things we’ve learned over the years then it would be hard for us to make any progress beyond that. Using AI coding tools can feel a bit like this today, where every new feature or bug fix requires the tool to re-learn how the codebase is structured, how a particular class or method works, what kinds of preferences you have, what CLI tools it has at its disposal and when they are helpful. The tool ends up spending quite a bit of work just to acquire the context it needs before it even gets to making meaningful changes.

But like so many things, if you look at it in the right light these problems aren’t new. When a new developer starts work on a new codebase or in an area of the code they haven’t worked in recently, they too need to re-acquire the context needed before they begin work. Whether human or AI tool, we need these connections to the past to understand the future.

When using AI tools (as without) lost context costs you time and money. The more research the AI tool has to do to learn your code structure the more money you’ll be spending in tokens that could have been used for more productive ends. If the tool then forgets what it’s learned from session to session (or even just when compacting memory) the time and money you spent on research is lost for any future use.

To help solve the human problem, we work to make our code easy to understand and add documentation to aid in the journey; documenting patterns and calling out pitfalls. I would put forth that we can leverage this same solution for AI and in the process help both machine and human get the knowledge and context they need faster.

Overall Strategy

We want our documentation to be there when it’s needed without being too heavy to consume up front. We could place all of our documentation in a single file (perhaps the main README) but that file is going to get really big really fast. You or the AI tool are going to need to sort through lots of irrelevant information to find what you are looking for and this gets expensive fast in either case. Instead, we want to make our documentation discoverable in the moment of need:

Inline Documentation: this will be our first line of defence. Documenting public methods and classes is going to be most discoverable and likely to stay up to date since it’s right next to the code it’s describing.
README for the project: This will serve as our main entry point. We’ll import it into tool specific files (like CLAUDE.md). It will contain references to other places things can be found in our documentation as well as describe our main documentation strategy.
READMEs in subdirectories: Sometimes subsystems have things we want to describe that are too specific for the main README but too general for in-inline documentation. For these, we can utilize READMEs in subdirectories that contain information specific to that area of the code.
docs/ directory: In many projects, you might choose to have a separate docs/ directory containing things like style guides and other general documentation. To make use of these, we can link back to them in the main README so they can be referenced as needed.
~/ENGINEERING.md: This file will be used to store your own personal engineering preferences so that AI codes more in your style. It’s also a nice chance to take stock of what principles are important to you. It can be included in local tool specific memory files like ~/.claude/CLAUDE.md to make the tools aware.
Project File: When working on a larger project, starting a file to contain your objective and progress can help AI stay focused on the task at hand and remember relevant information along the way.

Let’s look at these some more detail!

Inline Documentation

Inline documentation has been a best practice for a long time already to help share context with anyone reading your code; using AI tools only makes it more relevant. For our strategy it’s going to be our first line of defence. Any machine or human looking at the code is going to have that documentation available right there making it very discoverable. Since it’s right next to the code it’s discussing, it’s also much more likely to be kept up to date as the code changes.

As with any good inline documentation, avoid just describing the implementation but instead focus on documenting usage, examples, and gotchas. The documentation can also help point to other relevant classes using things like @see tags in Yardoc.

Not only can AI make use of the documentation to get context faster, it can also help keep the documentation up to date and appropriately document new public methods and classes!

We can make sure AI is aware of and uses inline documentation by making a note of it in our memory strategy described in the main README file that we’ll look at in a little more detail next.

Project README

We’ve been adding READMEs to our projects forever to help engineers get up and running quicker. We don’t need new tool specific solutions like CLAUDE.md, we just need make sure our AI tools know where to look for this foundational document!

When using Claude for example, this can be accomplished by importing the README into your project’s CLAUDE.md file like:

@README.md

Underneath that, you can still add anything that might be relevant for that specific tool in it’s tool file; but otherwise we’re now free to keep general project information in the main README where it can be used by any human or AI tool.

One thing that might be a helpful addition to the README is a specific section for AI tools to store their context in. Some of the things it might want to store might not make as much sense for a larger audience, so we can create a section of the README called something like “AI Context Notes” and then inform AI that this is the section it should feel free to store context in for later reference.

The README should list common commands to do things like start the server, run the tests, etc which also adds these things to AI’s repertoire. It can contain links to other documentation to make it more discoverable. It can also contain high-level descriptions of the architecture of the app and the major objects in it.

Let’s look at one possible example.

# My App Name

## Overview
Brief description of the app

## Getting Started
- How to get the project up and running

## Common Commands

### Running Tests
```bash
# Run all tests
bundle exec rspec

# Run a specific test
bundle exec rspec spec/path/to/test_file.rb

# Run tests with specific line number
bundle exec rspec spec/path/to/test_file.rb:42
```

### Starting Server
```bash
bundle exec rails server
```

## Architecture & Patterns
In this section, describe the major systems and objects as needed to give an overview of the app's architecture.

## Related Documentation
- **[style_guide_overview.md](docs/style_guide/style_guide_overview.md)**
- **[engineering_practices.md](docs/style_guide/engineering_practices.md)**: Development workflow and best practices
- **[ui_library.md](docs/style_guide/ui_library.md)**: UI components and design system

## AI Context Notes

### Memory Discovery Protocol
When working in any directory:
1. Look for inline documentation on the method or class
2. Look for README.md in current directory first
3. Check parent directories up to project root for additional context
4. Focus on "AI Context Notes" sections for AI-specific guidance
5. Reference @docs/style_guide/ files for coding standards
6. Update README files when learning new patterns

### Memory System Architecture
This project uses a hierarchical memory system:
- **Inline Documentation**: Documentation on public methods and classes describes usage and examples
- **Project Memory**: This README.md serves both humans and AI tools
- **User Memory**: `~/.claude/CLAUDE.md` for personal preferences
- **Directory Memory**: README.md files in subsystem directories
- **Memory Imports**: Use `@path/to/import` syntax for modular organization

This is really just an example and you should definitely make it your own in your own project. Be sure to consider what would be helpful to both humans and any potential AI tools. The cleaner and more organized and informative you can make it, the better for everyone!

The sections on memory discovery and architecture in the README are critical to what we are trying to accomplish. These sections make AI tools aware of where it can obtain memory files and the information it needs.

Subsystem README

As your app grows, you will likely get to a point where whole subsystems of your app may take quite a bit to explain on their own. Or potentially that part of the app contains a specific pattern you would like to see followed (like, for example, a directory containing web-components for the UI library). In cases like these, you can choose to create a README in that subdirectory. Here’s a quick example for one in the Web-components directory:

# Web Components

[Web components](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
make use of the browser native [customElements API](https://developer.mozilla.org/en-US/docs/Web/API/Window/customElements) to create custom elements to be used on a page just like standard HTML elements (or, in some cases, to extend existing HTML elements).

## Structure of this Directory

In this directory, you will find subdirectories that contain the JS and CSS to
define an individual component. There will also be a README file in that
directory with a description and examples of usage.

## Creating a new component

If you are creating a new component, you will need to import it's files in the
index.js and index.scss files found in this top level directory.

## AI Context Notes
- Some note based on something AI learned while implementing a web component

And here’s a possible example for a complicated subsystem:

# Payment Processing

## Overview
This module contains all code that pertains to the processing of payments (for plans, new products, etc).

## Quick Start
- Key files and their purposes
- Common operations
- Where to find examples

## Architecture & Patterns
- All payment processors should respond to `#process_payment`
- There is a shared spec example testing the interface for a payment processor in 'spec/shared_examples/payment_processor.rb'

# Related Documentation
- Links to @docs/ files
- External resources

## AI Context Notes

### Recent Patterns Discovered
- Pattern: New payment processors should use single table inheritance from the base PaymentProcessor

## Recent Changes
- We now explicitly round down to the nearest cent when calculating payments

Integrating Existing Documentation

Often a project will have other places documentation is stored and if you have that, let’s make sure it’s more discoverable by human engineers and AI by providing links! In some of the examples I referenced a docs/ directory. Perhaps in your project this directory contains style guide information as well as descriptions of various major systems. If you have this, be sure to place links to them in the readme that’s most appropriate so that they can be discovered and leveraged or updated as needed. You’ve already put the work in to create that documentation, make sure you’re getting all the use you can out of it!

By linking to your coding conventions and style guide docs in your project README, you’re helping your tools stick to the agreements you’ve made as a team and therefore reducing the amount of re-work you’ll need to do at the end.

Your Engineering Philosophy

Writing code isn’t a purely mechanical exercise, you as the author leverage your craft and experience to make it really shine. If you’re using an AI tool, you’ve experienced how much time you can lose trying to explain to it why it should favor one approach over another; or you’ve experienced the frustration of needing to manually clean up a less than optimal implementation from AI so that it matches your definition of good code.

To help avoid this round and round, we can help the tool better understand how to code in your style by creating an ENGINEERING.md that contains notes on all the things that are important to YOU as an individual engineer (and that AI can add to as it learns more about you). It can also provide an interesting point of reflection for you as you consider what your engineering philosophy is.

This can be a hard one to put together; I experienced a bit of writer’s block at the beginning. To help get me started I explained what I wanted to create to AI and asked it to interview me about my approach to engineering and what patterns were important to me, then assemble the results into an initial ENGINEERING.md. Doing this gave me a starting point, but I’m still not happy with the representation and want to go back and spend more time crafting this file in the future. Here’s an example of some of what is in my (far from finished) ENGINEERING.md:

# Ross Reinhardt - Engineering Philosophy

## Core Principles

### Object-Oriented Design First
I strongly favor proper object-oriented programming over procedural patterns. I actively avoid service objects as they become dumping grounds for procedural logic that obscures domain objects and concepts that should be modeled explicitly.

### Interface-Driven Development
I focus on the interfaces between objects and the messages being sent. I prefer "tell, don't ask" patterns - instead of querying an object and updating its state, I send it a message about what happened (e.g., `job_updated`) and let it handle the response.

### Command/Query Separation
- **Query methods** (return values) should have no side effects
- **Command methods** (side effects) should not return values we depend on
- Command methods often return `self` to avoid accidental dependence on return values

## Code Organization & Patterns

### Domain Modeling
When encountering business logic, I ask "who would I send this message to?" to identify the appropriate object. If no existing object fits, I look for new domain objects that emerge from the problem space.

### Rails/Ruby Preferences
- **Vanilla Rails/Ruby**: Stick to standard patterns whenever possible
- **Callbacks**: Use model callbacks with async processing to avoid blocking saves
- **Concerns**: Only use for clear, shared concepts (e.g., `Archivable`). Never as junk drawers to hide code
- **Helpers**: Rarely used, only for generic, reusable frontend utilities
- **Presenters**: For complex page-level view logic
- **Decorators**: Use SimpleDelegator for context-specific object behavior

### Architecture Guidelines
- Follow Sandi Metz's Rules for Developers
- Watch for Law of Demeter violations
- Prefer dependency injection to reduce coupling
- Avoid `stub_any_instance_of` and `stub_chain` - they indicate coupling issues

## Testing Philosophy

### Test-Driven Development
Always lead with tests, whether debugging or building new features. Start with "outside-in" approach:
1. Begin with failing feature test
2. Follow exceptions to lower levels (request specs, unit tests)
3. Work back "out" to ensure higher-level tests pass
4. Repeat cycle

### Test Organization
- **Feature specs**: Comprehensive but expensive - use sparingly for smoke testing happy paths
- **Request specs**: Integration-style testing for edge cases, preferred over controller specs
- **Unit tests**: Abundant and cheap for testing individual objects and edge cases
- **Test pyramid**: More unit tests at base, fewer integration tests, minimal feature tests at top

### Testing Patterns
- Use `describe` instead of `RSpec.describe`
- Keep nesting minimal - prefer flat structure over deep context nesting
- Factory preferences: `build` > `build_stubbed` > `create` (only when necessary)
- **Integration specs**: No mocks/stubs - test end-to-end system behavior
- **Unit specs**: Mock other objects, use as refactoring opportunity
- **Duck typing**: Create shared examples for any role-playing objects
- Use `instance_double` over generic mock objects

### Sandi Metz Testing Guidelines
- **Incoming queries**: Test expected results, don't test outgoing queries
- **Incoming commands**: Test direct public side effects
- **Outgoing commands**: Test that expected messages are sent
- Never assert on messages an object sends to itself

## Code Quality Standards

### Review Criteria
- Code is easy to understand and open to change
- No Law of Demeter violations
- Comprehensive test coverage
- Rubocop compliance
- Public methods documented with YARD (markdown format)
- Classes have top-level documentation

### Documentation Philosophy
- **YARD Documentation**: All public methods and classes require YARD documentation using markdown format
- **Focus on Usage**: Document **what** the method is for and **when** to call it, not **how** it works
- **Complete Tags**: Include proper `@param` and `@return` tags with types and descriptions
- **Context over Implementation**: Provide high-level context for consumers, not implementation details
- **Self-Documenting Code**: Code should be clear through names and structure
- **Minimal External Docs**: Avoid external documentation that can become outdated
- **Living Documentation**: Inline docs serve both humans and AI tools, update when understanding changes

### Red Flags
- Procedural code stuffed into service objects
- Violations of Sandi's Rules
- Heavy coupling between objects
- Missing tests or poor test quality

## Communication & Workflow

### Git Practices
- Clear, informative commit history
- Follow commit template guidelines
- Top-line summary + JIRA ticket + detailed body
- Commits should tell a story of the change

### Gem Selection
- Actively maintained and frequently updated
- High usage stats indicating community adoption
- Well-documented with clear APIs

### Performance Philosophy
- Optimize for readability first
- Only optimize for performance when absolutely necessary
- If performance optimization maintains readability (e.g., eliminating N+1), implement it

### Refactoring Approach
- Leave working code alone unless actively working in that area
- When making changes, evaluate if refactoring would make the change easier
- Refactor to improve understandability
- Use refactoring as opportunity to reduce coupling

## Development Tools & CLI Utilities

### JIRA CLI
I have the JIRA CLI configured locally, which AI tools should leverage for:
- **Ticket Research**: Retrieve detailed information about any JIRA ticket including descriptions, acceptance criteria, and comments
- **Context Gathering**: Understand requirements and background when starting work on a ticket
- **History Tracking**: Research the evolution of features or bug fixes through ticket discussions and updates
- **Requirement Clarification**: Access stakeholder feedback and technical discussions captured in ticket comments

### GitHub CLI (`gh`)
The GitHub CLI is available for comprehensive repository operations:
- **Pull Request Management**: Create, review, and research pull requests with full context
- **Repository Insights**: Understand project history, contributors, and development patterns
- **Issue Research**: Investigate related issues, discussions, and their resolution history
- **Workflow Automation**: Streamline common GitHub operations like creating PRs with proper templates and metadata
- **Code History**: Research commit history, blame information, and change context

### AI Usage Patterns
AI tools should proactively use these utilities:
- **Initial Research Phase**: When starting any ticket, fetch JIRA details and research related PRs/issues
- **Context Building**: Before making changes, understand the full history and requirements
- **PR Creation**: Use `gh` to create well-formatted PRs with appropriate context and links
- **Code Investigation**: Leverage both tools to understand why code exists and how it evolved
- **Documentation**: Reference ticket numbers and PR links in commits and documentation

#### RSpec Execution Preferences
When running RSpec tests, AI tools should optimize for token efficiency while maintaining useful feedback:

**Default Command Pattern**:
```bash
bundle exec rspec --format progress --deprecation-out /dev/null spec/path/to/file_spec.rb
```

**Rationale**:
- `--format progress` uses dots (`.`) instead of full test descriptions, reducing output by 40-50%
- `--deprecation-out /dev/null` suppresses repeated deprecation warnings that add noise
- For large test suites, this can save thousands of tokens per run
- Test descriptions are still visible in the spec file itself when context is needed

**When to Use Documentation Format**:
- Debugging failing tests where you need context about what was being tested
- Exploring unfamiliar test suites to understand coverage
- Override with: `bundle exec rspec --format documentation spec/path/to/file_spec.rb`

Both show the same essential information (2 passing examples), but progress format is dramatically more token-efficient for AI processing.

---

*This document captures my core engineering philosophy and preferences. It serves as a guide for how I approach software development and can inform AI tools about my preferred patterns and practices.*

Toward the end of this file, you can see that I also use this opportunity to inform AI of the CLI tools I make use of in my workflow and when they could come in handy so that it knows it can leverage them as well (without me constantly needing to remind it).

I’ve also noted some AI specific information at the end about how I want it to approach project, and ways it can run specs that reduce the output from the run to save tokens.

Project Files

The final type of memory I’m going to look at here is project focused memory files. For projects that span more than just some basic back and forth a project file can give be a helpful artifact to hold the context of that what it is you are trying to do. Without this, AI can start to forget what it was trying to accomplish or you can end up having to repeat a lot of context when a session gets interrupted.

I’ve experimented with two different approaches for starting a project:

The first approach would be to create the project document ahead of time giving an overview of the project, it’s goals, and a rough overview of what it would entail. This might be an artifact from your planning processes like a Project Brief document. When starting the project, you tell your AI tool to refer to that project document and save it’s context back to the file as it works.

Another way would be just to tell AI to create a file documenting the project plan when you are conversing with it about a new project. It’ll create a new file and use it to manage it’s memory of the current project. If you are coming back to a new session later, you can refer to that document in your prompt to quickly regain the context you had before in a previous session.

Using a project file on more complex projects can result in behavior that is more focused and less wandering. Once you are done with the project, you can just delete the project file as needed (or use it to have AI update related documentation/READMEs with relevant context before it’s deleted).

Checking Your Context

With all this work on memory files, it helps to know what context your AI tools have at that moment. If you are using Claude, you can run the slash command /context which will list in its output all the memory files it currently knows about. This can be helpful as you set things up to make sure the memory files are actually being picked up as you want them to be.

Remember Me to One Who Codes There

Using the strategies above for documentation that are mostly already best practices in our craft, we’ll be able to make use of AI tools in a focused, efficient, and tool agnostic manner.

Maintaining this documentation and saving learnings will become something we do regularly to continue to add value. In a future post I’ll look at some custom commands that we could leverage to help us with obtaining and saving these learnings from our sessions. In the meanwhile, I can share this post by Thomas Landgraf that I found inspirational and which discusses some custom prompts that can be used in these ways.

Done right, the value we build with this documentation will be something that benefits not just us, but our team, and even future engineers working on the code base we never meet. By leveraging classic and proven forms of documentation, these memories will survive the hype cycle for any particular tool and prepare us for a future yet unwritten.

Creating a Custom Git Commit Template

Thu, 03 Jun 2021 01:08:00 +0000

If you write commit messages every day, you might find it helpful to have a template to help you format your messages. I’ve found a template helpful for including the names of co-authors I work with often so that I don’t have to look them up every time and for making sure my commits follow the format expected by the rest of my team. Setting one up is very easy!

In this quick tip I’ll show you how to set a template for an individual repository as well as globally.

Local Commit Template

To set a template up locally, first cd to your project’s directory. Now create a template file at .git/.gitmessage.txt. The name of the template file can be whatever you want it to be as long as it matches what we set in the configuration later.

The contents of the template can also be whatever you want it to be! Lines that begin with a # are comments and will not appear in the final commit message.

Here is my current template. I pair often and so I include Co-authored-by tags for the people I commonly pair with. When I pair with one of them, I just uncomment the line for them (remove the #). In GitHub, Co-authored-by tags will make the pictures of collaborators appear on the commit with the main author, which is pretty cool. On my current team we will include a link to the story from our project tracking software in the commits, so I include a prompt for that in my template. I also included a link to a handy blog post as a reference for writing good commit messages.

Story:


# Co-authored-by: Bea <bea@acme.com>
# Co-authored-by: Abby <abby@acme.com>
# Co-authored-by: Juan <juan@acme.com>
# Guide: https://thoughtbot.com/blog/5-useful-tips-for-a-better-commit-message

Now, set this file as your commit template for the current repository using:

$ git config commit.template .git/.gitmessage.txt

The next time you make a commit in that repo, (eg. git commit) you will see your template when Git opens your editor for creating the commit message.

Global Commit Template

Recently, I’ve been working on several projects across several repos and I didn’t want to have to set up the same template in each. Thankfully, we can set up a global template!

This time, we’ll put the template file in the home directory ~/.gitmessage.txt and then set our global git configuration to look for it:

$ git config --global commit.template ~/.gitmessage.txt

That’s it! Local git configuration supersedes global, so if you want to add local templates on specific repos you still can and they will be used instead of the global template.

Stubbing and Mocking in MiniTest

Tue, 25 May 2021 03:16:00 +0000

When I started using MiniTest one of the things I struggled with was how to mock and stub objects when constructing my tests. Here are a few patterns I’ve collected over time and now find helpful when stubbing and mocking in MiniTest.

Basic MiniTest Stub

MiniTest comes with a way to stub a value for a test. Here is a classic example stubbing time:

Time.stub :now, Time.new(2012, 11, 14).utc do
  MyObject.new.are_we_there_yet?
end

In this example, the :now method on the Time object is stubbed so that it always returns the same time while testing MyObject.

#stub takes a few arguments, the first is the method you wish to stub and the second is the value it should return when it’s called. This second value can also be an object that responds to #call and if it does the return value is the result of calling the object. Which leads us to a second pattern.

Turn Your Stub Into a Spy

Since we can supply an object that responds to call for our stub, let’s turn our stub into a “spy”. Spies not only return a canned answer but are concerned with how they are called. To do this, we can use a Ruby lambda. Inside of our lambda we’ll make some assertions about the arguments the stubbed method is called with.

test "Disabling Alerts" do
  command = AlertsPause.new(user)
  response = nil

  args_checker = lambda do |args|
    assert_equal "1234qwfp", args[:user_id]
    assert_equal "team1234", args[:group_id]
  end

  Connection.stub :disable_notifications, args_checker do
    response = command.response
  end

  assert_match(/paused alerts/, response[:text])
end

In this example we are using a lambda to ensure that disable_notifications gets called with the expected arguments. When the disable_notifications method is called on Connection, args_checker will be called with the arguments passed to that method. Inside the lambda we use assertions to “spy” on the caller of this method and make sure it passes us the arguments we are expecting.

One other thing to note here, if you are using this approach and want to make assertions on the result of something called within the stub block, you have to declare the local variable before the block for it to be available in the scope outside of the block. In this example response is used in this way; it is declared and set to nil at the beginning of the spec, assigned in the block, and the used in an assertion at the end.

MiniTest::Mock

MiniTest::Mocks are object doubles you can use as a stand-in for some other object. Their use is really simple:

status = MiniTest::Mock.new
status.expect :fine?, true
checker = EverythingsFineChecker.new(status)

checker.is_everything_fine?
# => true

status.verify

We can use #expect to stub methods and set return values on our mock object. If we want it to spy for us, we can call verify at the end to make sure that the stub was actually called. The first argument of expect is the method to stub, the second is the value to return, and the third is optional and can be an array of arguments. If we want to stub a method set_speed that accepts an argument of speed, we might do it like this for a speed of 55:

car = MiniTest::Mock.new
car.expect :set_speed, car, [55]

Return a MiniTest::Mock from a Stub

You can combine stubs and mocks! In this example, a client is stubbed so that it returns a mock client when it’s initialized. The mock_client is stubbing a call to list_all to always return an empty array.

mock_client = MiniTest::Mock.new
mock_client.expect :list_all, []

Client::Request.stub :new, mock_client do
  # do something using the client
end

Using Standard Ruby Objects as Test Doubles

We can also use plain old Ruby in our test! One example of this is using a test object created in the test as a stand-in for something else. Here we create a mock client object that responds to list with some pre-canned answers and then use dependency injection to pass it into our job instead of one that might make real requests to an API

class ProcessingTest < MiniTest::Unit::TestCase
  class MockClient
    def list(page:)
      case page
      when 1
        ["item 1", "item 2"]
      when 2
        ["item 3", "item 4"]
      else
        []
      end
    end
  end

  test "Process Items" do
    ProcessingJob.new(client: MockClient.new).perform

    # assert something
  end
end

Redefine Methods on Ruby Objects

Here is a cool trick you might remember from another one of my recent posts, using plain Ruby you can redefine a method on any object. We can use that in a test to stub methods! Here is an example of stubbing some methods on an instance of team, one of which raises an exception.

team = Team.create(name: "Engineering")
def team.active?; true; end
def team.add_member(*args); raise TeamError::NotAuthorized; end

TeamFinder.stub :engineering_team, team do
  # Do something
end
# assert something

In that example, team is stubbed so that it always returned true for active? and so that it will raise an exception when calling add_member.

The syntax is a little weird at first, but you’re likely familiar with defining class methods like:

def self.say_hello
  puts "hello"
end

This is the same thing! self in this case refers to the instance of class representing the object and you are defining the “say_hello” method on it.

Using this technique is pretty powerful because it lets you quickly stub methods on any object and is especially handy when you have several methods to stub. The cool part is, it’s just Ruby!

Use The Tests, Luke

There are some patterns I’ve found helpful when writing tests in MiniTest. If you find that you are having to stub and mock a lot or that you are stubbing things to return other stubbed things that return other stubbed things it could mean that your class knows too much about other objects in your system. I’ve found it helpful to use this pain when I encounter it as an indicator that I should re-consider some closely coupled objects and find ways to make them less coupled.

Git Autostash

Wed, 31 Mar 2021 02:47:00 +0000

Today I Learned: git rebase –autostash

Rebasing is something I do often in Git. The most common time is when I’m updating my branch with the latest “main” branch; I’ll typically use a rebase strategy on pull to avoid creating extra merge commits and to help keep a clean history. Often I’ll have uncommitted changes in my worktree that need to be stashed before I can do a rebase so I do something like:

$ git stash
$ git pull --rebase . origin/main
$ git stash pop

Well today, I was looking in the help documentation for rebase (git rebase -h) and stumbled on the --autostash flag. According to the docs it will:

Automatically create a temporary stash entry before the operation begins, and apply it after the operation ends.

Nice! This is a nice shortcut for exactly what I was doing above! I can now do the same thing using:

$ git pull -r --autostash . origin/main

It’s also possible to set this up as a default mode for every rebase if you should desire in your git config using the merge.autoStash variable:

$ git config merge.autoStash true

The Return of the Eigenclass

Mon, 22 Jun 2020 15:33:00 +0000

So many times once I’ve learned how to do something, I’ll find myself doing it but maybe not fully understanding what I’m doing. Ruby class method definitions are one of these things for me; I do it all the time but it wasn’t until recently that a light bulb went of and I reached a deeper understanding of what I was REALLY doing. Here is that journey, which started with looking for a way to stub methods in ruby tests.

Taking a Shortcut

While writing some tests in Minitest, I was looking for a way to stub methods on an instance of an object either because the method has side effects I want to avoid in my test or because I want to control the environment of the object under test. Let’s say we have two classes, Runner and Race. We want to test Race, but don’t want all the runners to have to run the full marathon for this test. The implementation could look like:

class Runner
  def initialize(name)
    @name = name
  end

  def run_marathon
    puts "#{@name} is running a long way"
  end
end

class Race
  def initialize(runners)
    @runners = Array(runners)
  end

  def start
    @runners.each(&:run_marathon)
  end
end

runner_m = Runner.new("Martin")
runner_l = Runner.new("Lila")

Race.new([runner_m, runner_l]).start

Running this file gives you:

$ ruby ./runners.rb
Martin is running a long way
Lila is running a long way

Both runners are running the full race. You can “stub” a method on a ruby object by redefining it on the instance of the object. We’ll use this method to make Martin take a shortcut.

class Runner
  # Runner hasn't changed...
end

class Race
  # Race hasn't changed...
end

runner_m = Runner.new("Martin")
runner_l = Runner.new("Lila")

# Make Martin take a shortcut
def runner_m.run_marathon
  puts "#{@name} is taking a shortcut"
end

Race.new([runner_m, runner_l]).start

Running the file now shows Martin taking a shortcut

$ ruby ./runners.rb
Martin is taking a shortcut
Lila is running a long way

Bringing the Class

This is pretty cool! We are using plain old ruby techniques to stub #run_marathon for Martin so that he doesn’t have to run the full marathon! This is now my go-to stubbing method when writing tests in Minitest or TestUnit. But I recognized that def object.method syntax from somewhere, hmm. Oh yeah! Defining a class method like def self.method. This is something we all do every day! Let’s improve the API of our runner object to add a ::named class method we can use to initialize a new runner instead of calling ::new directly.

class Runner
  def self.named(name)
    new(name)
  end

  # The rest of Runner...
end

class Race
  # Race hasn't changed...
end

runner_m = Runner.named("Martin")
runner_l = Runner.named("Lila")

Race.new([runner_m, runner_l]).start

Running this we get

$ ruby ./runners.rb
Martin is running a long way
Lila is running a long way

Great! Everything in Ruby is an object; here Runner is an instance of Class. We can use the same notation that we used to redefine a method on an instance of Runner to redefine a class method on Runner because it is itself an instance of the Class object.

class Runner
  # No change...
end

class Race
  # No change...
end

def Runner.named(name)
  new(name + " (participant)")
end

runner_m = Runner.named("Martin")
runner_l = Runner.named("Lila")

Race.new([runner_m, runner_l]).start

$ ruby ./runners.rb
Martin (participant) is running a long way
Lila (participant) is running a long way

We’ve redefined the class method to have “(participant)” after each of the names. What we did here was open up the “singleton” object Runner and change the named method. A singleton is a “pattern that restricts the instantiation of a class to one “single” instance” (wikipedia); so there is and will only ever be one instance of Class representing Runner. When we first load our ruby program a single instance of Class is created for Runner and is accessed via the Runner constant. These single instances are also called “metaclass” or “eigenclass” (eigen - “own” or “individual”) which are also pretty cool sounding. I might actually watch something called “The Return of the Eigenclass” (would the return just be self? lol).

Here, saying def Runner.named looks pretty weird. But when used inside a class it looks very familiar to many Rubyists. The way we initially defined ::named is doing this very thing using self (and self just represents the singleton Runner)

class Runner
  def self.named(name)
    new(name)
  end

  # The rest...
end

It turns out, this is common enough that Ruby provides a notation for this. Instead of using def Runner.named we can use class << object. That’s class << followed by the singleton object.

class << Runner
  def named(name)
    new(name + " (participant)")
  end
end

This leads us to the final step in the journey; understanding the class << self syntax. I have often seen and understood it as an alternative to writing def self.method, but I never really felt comfortable with it.

When we use the class << object notation inside of the runner class we can use self and so it becomes

class Runner
  class << self
    def named(name)
      new(name + " (participant)")
    end
  end

  def initialize(name)
    @name = name
  end

  def run_marathon
    puts "#{@name} is running a long way"
  end
end

So now it’s clear; what we are doing here is just opening up a singleton representing the Runner object so that we can add methods to it using that special Ruby syntax for doing so and just like we did with our more literal def Runner.named example. Since we are actually inside the Runner object, we can use self to access the singleton. Although the syntax is a little more intimidating at first, it’s not as scary once you understand what it’s representing.

The Journey’s End

This is what clicked for me! Just like redefining a method on an instance of Runner (like we did to make Martin take a shortcut), we are “opening up” the singleton representing Runner to define additional methods (class methods; or methods on the Runner singleton).

After discovering this and feeling more familiar, I’ve actually started to prefer it. For one, you don’t have to type self. as a prefix for each of the class method names. It also keeps the class methods nicely grouped together. Where it really shines for me is when I want to define private class methods.

class Runner
  class << self
    def named(name)
      new(name + suffix)
    end

    private

    def suffix
      " (participant)"
    end
  end

  def initialize(name)
    @name = name
  end

  def run_marathon
    puts "#{@name} is running a long way"
  end
end

We can use the private keyword just like we would in any other Ruby class! This came in handy when I had some complex Rails “scopes” I was defining (they are defined as class methods) and I wanted to break some of the logic out into their own methods for understandabilty (but keep them private, so that they weren’t exposed to the public API).

We now have a great way to stub methods using plain old Ruby, a better understanding of the class << object notation used for accessing the singleton class of an object instead of using def self.method, and another great tool in our Ruby toolbox that we can use whenever we need to redefine a method on any instance of an object.

Git Strategy For Pair Programming

Thu, 07 Nov 2019 00:00:00 +0000

I’ve recently been doing a lot more pair programming than I have ever done. Most times we will be sharing a branch and will switch drivers by committing some code so the new driver can pull it down and take over. This works great, but it can start to lead to a messy commit history. After much experimentation I really like our current workflow and thought I’d share it! There are things here that apply even if you don’t pair program but will still help you tell a clear story for future developers with your git history.

First, What Does This Look Like With One Person?

A good place to start is with what my git workflow looks like when I’m working by myself. It’s important to me that when I’m done working on some code my git history tells future developers a clear and comprehensive story of why I did what I did so that when they git blame those lines of code what they find helps them understand why that code is the way it is. Because of that, when I’m done working on something I make sure that work is grouped logically into commits (or just a single commit in most cases) using an interactive rebase.

Let’s say I have 3 commits on the branch I’m working on:

$ git log --oneline -n3
2b010a4a1f (HEAD -> hard-work) One last tweak
e7bf81daa9 Woops, fix spec
3a26300ae4 Fix the bug that caused X

I have an initial bug fix commit that will have a descriptive commit message, but then I have two follow up commits with less than ideal temporary messages. When I am done with work I can do an interactive rebase using the git rebase -i origin/master. This will drop me into the default editor I have configured in my shell with something that looks like:

pick 3a26300ae4 Fix the bug that caused X
pick e7bf81daa9 Woops, fix spec
pick 2b010a4a1f One last tweak

# Rebase dd071b1302..2b010a4a1f onto dd071b1302 (3 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup <commit> = like "squash", but discard this commit's log message
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
# .       create a merge commit using the original merge commit's
# .       message (or the oneline, if no original merge commit was
# .       specified). Use -c <commit> to reword the commit message.
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out

There are some helpful instructions in the comment. What I’ll choose to do here is “fixup” the two commits I don’t want to keep separate which will make them a part of the one that I want to keep. I’ll designate the one I’m keeping by leaving it with “pick”. Additionally I have the option to reword that main commit if I change that “pick” to a “reword”. So now I’ll have:

pick 3a26300ae4 Fix the bug that caused X
f e7bf81daa9 Woops, fix spec
f 2b010a4a1f One last tweak

After doing that, all my work is now in one unified commit with a helpful message for future developers to discover.

$ git log -n3
commit 3735ddb5e50316869ec3b96974dd2babee0801f1 (HEAD -> hard-work)
Author: My Name <me@gmail.com>
Date:   Thu Nov 7 09:35:18 2019 -0500

    Fix the bug that caused X

    Story: link to story

    More information on why this change was made

# Other unrelated commits

That works, but git has some features that can help us with this workflow to avoid having to name commits that we have to manually fixup later. There are flags you can pass to git-commit to tell it that you either want to --fixup or --squash this commit automatically. For those commits I added after the main one, I could have done git commit --fixup 3735ddb5e50316 where that numbers and letters are the SHA of the main commit. No throw away commit message needed! If I had done this, I would have a git history that looked like:

$ git log --oneline -n3
4a5e93e675 (HEAD -> hard-work) fixup! Fix the bug that caused X
95e48fd49a fixup! Fix the bug that caused X
3735ddb5e5 Fix the bug that caused X

Awesome, this signals our intention for these commits as fixups. The real magic comes in when we rebase using the autosquash option git rebase -i --autosquash origin/master. Now, since we have already signaled that those commits will be fixups, the interactive page we are presented with will already list those commits as fixups!

pick 3735ddb5e5 Fix the bug that caused X
fixup 95e48fd49a fixup! Fix the bug that caused X
fixup 4a5e93e675 fixup! Fix the bug that caused X

Sometimes, I’ll skip the middle step entirely and if I make a change after making my initial commit I’ll just use git commit --amend to immediately make my changes a part of the original commit. Note that if you are using --amend or rebase you will need to force push your branch using git push -f and if someone is working with you on this branch, they will not be able to just pull the branch down using git pull (but more on that next).

That is my basic daily workflow in Git. There are great resources out there with more detail on autosquashing, writing good commit messages, and setting up templates for your commit messages that I have found helpful toward the end of effectively telling a story with my git history.

But What About Pairing On The Same Branch?

Whether you are actually pairing or if you are just reviewing someone else branch locally, using --amend and rebase can change how you need to approach retrieving the latest work from the shared repository. The reason is because those commands “re-write history” in git. If someone else has an old copy of your branch locally, this can cause problems because git now can’t figure out what it should do because the two histories are different. Typically, re-writing history is considered a “Bad Thing” for any shared branches because git can no longer figure out accurately where the common histories diverge. Assuming though that we are working on a PR that hasn’t been merged into a larger shared branch (like “master”) it’s our chance to craft the history before it’s set in stone by being merged and shared.

When pairing, if we want to switch drivers what options do we have?

Option 1 is to use fixup commits as shown above. Using this option allows us to commit a chunk of work with the intention to clean it up later and we can still git pull the branch down until it’s rebased. One time this is particularly useful is when you are pairing and someone has to step away. In that case, it can be helpful to put the changes in a fixup commit so that when they come back they can clearly see what has changed. This can also come in handy during an asynchronous code review when you make a change based on some feedback you receive. If you put it in a fixup commit, it’s clear to the reviewer both what changes where made and the intention to clean up the commit when the collaboration is finished.

But having a bunch of fixup commits would start to get annoying and make merge conflict resolution more difficult if that was our only tool. Option 2 is to just go straight to using --amend on the main commit when it’s time to switch drivers. Here is the key though, the new driver won’t be able to just pull the branch down using git pull because the commit was changed. What we really want to do is just reset what we have locally to be the latest version in the remote repository and we can do just that! Here is what that looks like:

# Time to switch drivers.
# Let's assume you already have already made the first commit and we are adding to it.
# On the current drivers machine run:
git ci --amend
# Change the message or don't and save
git push -f

# Now on the new driver's machine on this same branch
git fetch
git reset --hard origin/branch-name-here

That’s all there is to it! It’s key that you make sure to fetch before resetting though to make sure you have the latest they just pushed up. There are a couple of shortcuts you can use here. First, if you don’t want to edit the commit message now you can skip that step using git ci --amend --no-edit. If the upstream branch is configured for your current branch there is a shortcut there too. Instead of typing out the branch’s name you can use @{u} (think u for “upstream”). Now we have:

# Current driver
git ci --amend --no-edit
git push -f

# New driver
git reset --hard @{u}

If you need to set the upstream, you can run git branch -u origin/my-branch-name

Once Upon A Commit

Those are some tricks and tips I’ve learned while trying to pair and still tell effective stories with my git history. Just remember, be careful when using commands that re-write history. They are great tools when you are working on a branch that is not branched off of by others but be aware that these tools are “sharp knives” and can cause a headache if you use them on a branch others are building off of (like master).

If you are careful to craft your commit messages to tell a clear and comprehensive story, maybe you will be the future developer to be pleasantly surprised by a well written message and cohesive changeset when you git blame a mysterious line of code you are working so hard to understand and debug.

Low Pain Data Migrations In Rails

Wed, 30 Jan 2019 00:00:00 +0000

In search of a good way to update existing data in a mature Rails application

There have been many times where I’ve encountered the need to change some data in response to a change our application. As the project and team I’ve been working on have grown the need for a robust method to run these data migrations has as well.

What I’m referring to as a “data migration” is just some code that makes changes to data in your system. It’s not making changes to the actual structure of your database, but changing the records in it. For example, maybe you had some data stored as an attribute on a model but now that same information is being moved out to a related record. That is to differentiate it from a “Rails migration” which is just the normal migration files that you use in your rails app for managing the state of your database.

I’ve been looking for a way to do data migrations that:

runs automatically in most environments including developer’s local environments and non production environments to reduce burden imposed on the team
can run alongside production traffic without interruption
provides the option to run the migration on demand in production separate from deploys so that we could run the migration at an off time without having to perform a full deploy
allows the Rails migration to continue to work without updating if the code for the data migration changes or is removed
is easy to test

Rake tasks are a handy way to run some code in a testable way; what if we called a rake task from a migration? That seems like a good place to start! Putting the data migration in a rake task would also help isolate the rails migration from the data migration code itself (which in some cases might included calls to an external library that could break if the library’s API changed or we stopped using the library). It can be a pain to have to go back and update old migrations just because a method or a class changed names in your code years after the migration was run.

Here is a first attempt at our rake task data migration:

class CreateFooBarPermissionParity < ActiveRecord::Migration[5.0]

  def up
    say_with_time "Creating parity between old and new verions of foo bar permission" do
      Rake::Task["permission:create_foo_bar_parity"].invoke
    end
  end

  def down
    say "Nothing to do"
  end
end

say and say_with_time are just helpful little methods that ActiveRecord::Migration provides us to output information from our migration. If we tried to run the migration after the rake task had been removed, we would get a helpful error telling us that the task could not be found (but the migration would still break because of the missing task). Since running migrations is a normal part of a Rails application’s life cycle, this method has advantages over a stand alone rake task because we do not need to remember to run it manually in all environments; our data migration code would be run when the rails migrations are run as a normal part of the life cycle of your app.

Putting the data in a temporary rake task has other advantages as well. If the need arises later to re-run the task to fix an issue we can call our task from the command line ad hoc. The task can also be used as a tool while you are working on the feature! Many times while working on a feature I might end up with my local data in a crazy state and having the rake task to call and get my data back in a particular state can be really helpful. For me the rake task has been easier to test as well; while you can write tests for migrations it feels more intuitive to me to write a spec for a rake task containing the data migration.

Just using the rake task in the migration helps us meet several of the goals we had for our data migration! An important one to consider next is that when this data migration runs in production it should not interfere with production traffic. Since each rails migration runs in it’s own transaction by default, there is the potential that we could create locks in the database during a long running data migration that could tie up records in the database and have a noticeable effect our our users. That would happen because the production traffic would be forced to wait on any records it needed to access while our giant migration transaction finished. Yikes! I can say from experience that this leads to Bad Things :-). To avoid this it would be a good rule of thumb to disable the transaction that surrounds the rails migration so that we can handle adding transactions explicitly where they are needed for either data integrity or performance (care should be given though that the transactions are as small as possible if you need them at all). You can do this by adding disable_ddl_transaction! to the top of your rails migration. Now we have:

class CreateFooBarPermissionParity < ActiveRecord::Migration[5.0]
  disable_ddl_transaction!

  def up
    say_with_time "Creating parity between old and new verions of foo bar permission" do
      Rake::Task["permission:create_foo_bar_parity"].invoke
    end
  end

  def down
    say "Nothing to do"
  end
end

While it’s nice that we get a helpful error message if the rake task no longer exists and the Rails migration is run, most of the time a data migration is just needed to update the state of existing data in the database and will be completely removed when we are finished with it so it would be nice if we handled this common situation gracefully. We can handle this case by rescuing the exception and outputing a message from our rails migration. A missing rake task will raise a generic RuntimeError which is not specific enough to target (we don’t want to rescue all RuntimeErrors), but what we can do is match on the message from the exception to make sure that it’s coming from a missing rake task:

class CreateFooBarPermissionParity < ActiveRecord::Migration[5.0]
  disable_ddl_transaction!

  def up
    say_with_time "Creating parity between old and new verions of foo bar permission" do
      Rake::Task["permission:create_foo_bar_parity"].invoke
    end
  rescue RuntimeError => e
    raise unless e.message =~ /^Don't know how to build task/

    say "Rake task 'permission:create_foo_bar_parity' did not run because it doesn't exist"
  end

  def down
    say "Nothing to do"
  end
end

Sometimes we would prefer to run a data migration at an off time in production just to play things safe (nobody likes to watch the app go up in flames). But we would still like it to run automatically in all of our other environments that are not production and might have less traffic and risk. For this purpose, we could check for an environment variable and if we find it we would skip running the rake task in that environment with a message reminding you to run it manually. This would allow us to define which environments it should not run in as a part of the rails migrations while still allowing it to run by default in all other environments. That leads us to this final iteration:

class CreateFooBarPermissionParity < ActiveRecord::Migration[5.0]
  disable_ddl_transaction!

  def up
    if ENV["SKIP_DATA_MIGRATIONS"]
      say "Skipping rake task, please run 'permission:create_foo_bar_parity' manually"
    else
      say_with_time "Creating parity between old and new verions of foo bar permission" do
        Rake::Task["permission:create_foo_bar_parity"].invoke
      end
    end
  rescue RuntimeError => e
    raise unless e.message =~ /^Don't know how to build task/

    say "Rake task 'permission:create_foo_bar_parity' did not run because it doesn't exist"
  end

  def down
    say "Nothing to do"
  end
end

You could make the name of the variable what ever works best for you. With that environment variable set, we can deploy at a hight traffic time to production without effecting users and run the data migration at night when traffic is slower without needing the full deploy process. We may not need this option in all cases, but it’s nice to have it if we need it; especially if your process for deploying code requires some work.

This configuration has helped me get as close as I’ve ever been to having a painless way to update data across multiple environments. Hopefully some of the ideas might prove helpful to you too!

Resources For Learning To Program

Sun, 18 Feb 2018 00:00:00 +0000

Learn to program using (mostly free) resources available online

There are so many wonderful resources that are available to someone who is wanting to enter the world of being a programmer. But sometimes it can be daunting to know what is good, where to start, and what kind of path to follow through these resources. When I was just beginning to get interested programming, I didn’t have the funds or time for a boot camp since I needed my day job as a source of income; but I was fortunate to be able to pull on resources I could find on-line and experience from mentors to begin my journey into programming. It wasn’t easy, but it was possible and so worth it!

The Resources

These are things that were helpful to me as I launched into learning Ruby and becoming a web developer, so pick and choose as you find your own path!

You will need a robust text editor. This is the tool that you will use to craft your raw material as a programmer, and you will always be tweaking and improving it to fit your needs. Atom is an excellent choice that comes preconfigured in smart ways and is approachable.

At the very start www.codecademy.com is a great resource to just explore some of the very basics. They have some great programs now that lead you through building a website from scratch, for example. You can also pick and choose individual courses as well; maybe you want to just explore Ruby or JavaScript.

Once you start to get your sea legs, you will probably be looking for a bit of a challenge to expand your new skills. A great thing for this is exorcism.io. It’s like a collection of puzzles that you can solve while learning specifics of a new language. It’s still my go to when learning a new language (or just for fun :-))

All through your programming career it will be important to know where to look for help on an issue, and the beginning is no exception. Documentation for your language or framework is one place to find answers; another is your favorite search engine! Searching for an error message or issue can often turn up other people who have encountered the same problem. In addition, there is a whole community of people that ask and answer question on Stack Overflow. Many of the problems I encounter every day as a programmer I can solve by drawing on the knowledge of others on there.

Now for one of my favorites! Michael Hartl’s Rails Tutorial was absolutely essential in my journey. This one is Ruby and Rails specific, but even if that is not your jam there is still value in working through this tutorial. What makes it such a masterwork is that not only does Michael teach you the Rails framework, but he helps you learn what it means to be a developer. He walks you through what it’s like to develop an application as you would in the real world. He teaches you about using essential tools like version control (git), Github/ Bitbucket. The course helps you turn the skills you are building into a cohesive package. This amazing free (!!!) resource is like having a mentor walk you through building your first web application.

After working through the above, you will be off to a really great start! At this point, it really helped me to just start getting my hands dirty with some “real” applications. You can work on an idea that you might have, or just explore building something. It is super helpful to work on something with more experienced developers; whether that is contributing to open source or finding someone who is willing to mentor you as you contribute to their codebase. This feedback from others will be one of the best educations you will be able to get, and it will be way more engaging to be working on “real” things. Learn how to find answers to things that you don’t know, ask questions, and know that you will always be learning. These things continue to be important to me today!

At this point you can make things that “work”, now it’s time to make things that work even better and are easy to maintain. Any book by Sandi Metz is worth the read and will change the way that you look at the code you write. She also has a free newsletter that has great insights. There are an abundance of conference talks that have been recorded and made available online; these are a goldmine of information just waiting to be viewed! You can search in confreaks or on YouTube for recent conferences you are interested in. If you do happen to be looking into Ruby and Rails, RailsCasts is an amazing resource! Ryan Bates created a trove of screencasts many things you would want to do when building a Rails app. It might be getting a bit dated now, but much of it is still very relevant and he’s now made it available for free!

This is far from an exhaustive list (and is a little skewed towards Ruby), but these are some great resources to propel you forward. I wouldn’t be too strict on order; you may need to jump around, speed up, or slow down. Go at a pace that works for you and keeps you engaged.

Being My Own Biggest Obstacle

For me, the hardest part at the start of the journey wasn’t even a technical one. It was one of building confidence. Hearing others around around you that are further along in their journey talk about things that sound like another language can be intimidating. Take those opportunities to ask questions and build your knowledge! People who aren’t jerks will love the chance to explain. Since you will be learning on your own, building relationships with other people that do what you want to do will be an essential part of your learning and will be your ticket to finding jobs as well (if that is what you are going for). One great way to do this is to look for meetups in your area that you can attend. Be sure to search the interwebz for something called “imposter syndrome” so that it doesn’t slow you down and you can be comfortable being at the beginning of your journey. Although it can be hard to learn these things on your own, learning to solve problems for yourself will continue to serve you well beyond the beginning. You’ve got this!

All My Work Will Be Destroyed; a story of inspiration

Thu, 11 Jan 2018 00:00:00 +0000

You could hear no breeze in the tops of the trees bordering the edge of this 5 acre plot. The only motion in the atmosphere around seemed to be the waves of heat rolling off of any exposed surface, distorting the visible edge of everything so that we seemed almost in a hazy dream land. My hands moved automatically performing one of several yearly adjustments on the grapevine in front of me; adjustments that were crucial to the quality of the harvest but right now seemed trivial compared to the travails of performing them. On an acre of vines planted this way there are exactly 545 vines; that meant that on this 5 acres my coworkers and I had to repeat this operation 2725 time in the blazing sun. After these 5 acres where done there where 50 more, or somewhere around 27250 more vines to go.

The vines were arranged in rows about 8 feet apart and at this point of the season meant that they formed a curtain of foliage about 6 feet high and effectively blocked you from seeing much else than the far off ends of the rows and the blazing sun above. Through this curtain of foliage in both directions I could here a persistent rustle mimicking the sound of my own work. Today the normally ubiquitous low hum of talk was absent; lost is the hot vapors that swirled around us. The grapes don’t develop properly without the proper sun exposure and air movement and so today I had led our team of 6 out into this field to make those adjustments.

We all reached the end of the rows around the same time and looked in vain for a little shade under the vines to sit in while we guzzled more water. Looks of exhaustion marked everyone’s sweaty, beet red faces. Looking behind me at the long line of row yet to go and then back at our group I was thankful for their determination to get to this point but wondering how we would meet the challenge ahead of us. We started making small talk and laughing together a bit. This was the summer where “Gangnam Style” was going viral and in jest one of the team started the song on his cell phone. There in the grassy area between the end of the rows and the edge of the woods and delirious from the heat and the absurd difficulty of it all, we broke out into an impromptu dance party while the tinny cellphone speaker belted out this unique specimen of k-pop. After this unexpected interlude and laughing heartily at each other and ourselves we met the challenge ahead of us and plunged into the next rows to begin again. The fate of that vintage and whether we met our quality goals are foggy in my memory, but what stuck with me was the bond that team formed in the crucible of these experiences. Those people and what we experienced will be vivid in my memory for much longer than the things that otherwise seemed so important at the time.

Now I work in software, but I see vestiges of these dynamics there as well. The crucible is not environmental (usually) but complicated technical challenges and lofty goals of other sorts. The importance of these human connections remains something that inspires me. To be honest, the feeling is not nearly as intense as when you are experiencing harsh physical challenges together as a team; that is indeed a special feeling reserved as a reward in proportion to the suffering incurred. But the patterns are there, and the impact that we will have on those around us is real.

Early in my career as a software engineer there were people who were willing to be there for me as I struggled to find my footing in a new industry. As I progressed in my understanding, there were people who were much more experienced and were willing to help me form my own insights and greater understanding. I feel like I am finally in a position where I feel reasonably confident as I continue to learn and face new challenges and in this new position it is a great joy now to be able to be that person that can help others in their own quests for understanding.

One tradition that I particularly relish is gathering around a table with our various brown bag lunches and talking about life. Not work talk, just being humans together. For better or worse, we are all going to leave marks on the lives of our coworkers. It seems to me the presence of these connections that come from being individuals that are brought together to work towards a common goal contribute in a large part both to our success as a team but also and perhaps more importantly they will leave lasting impression on us as people.

All the work that we are doing now will fade away. The grape vintage will be consumed, the difficult new addition to the app that is so critical today will be destroyed tomorrow. Even the team we are working with now will likely look different or cease to be at some point. The more enduring mark is not found in the product of the work that we are doing today, but in the marks we leave on the people around us and through them on the world around us while doing this work. I am inspired by those that have recognized this and left their mark on me; and in turn I am inspired to keep this awareness and think about what kind of marks I might be leaving on those around me.

Testing Pundit Policies

Thu, 21 Jul 2016 00:00:00 +0000

CanCan has been an awesome standby for authorization in many of the projects I’ve been involved with; but I’ve had my eye on Pundit and really appreciate the ‘just plain old Ruby objects’ approach. So on a couple of recent projects I made the jump. So far, it’s been awesome; but that’s a post for another day :-).

One of the first challenges that I ran into was developing a strategy for testing my policies. Both of my projects are using MiniTest, one uses spec via the ‘minitest-spec-rails’ gem and the other is just plain vanilla with the additions that Rails provides. FactoryGirl is used in both cases.

General Structure

In each policy test, the basic structure I’ve begun using is

# MiniTest
require 'test_helper'

class SomethingPolicyTest < ActiveSupport::TestCase
  setup do
    # Setup needed for all tests... maybe build different record for testing
    # against
  end

  test 'a user can' do
    # test the things a user can do
  end

  test 'a user can not' do
    # test the things a user can not do
  end

  test 'user scope' do
    # test the scope of a user
  end

  test 'an admin can' do
    # test the things an admin can do
  end

  # ...
end

#MiniTest::Spec
require 'test_helper'

class SomethingPolicyTest < ActiveSupport::TestCase
  let(:something) { build :something }
  let(:another_something) { build :another_something }

  describe 'user' do
    let(:user) { build :user }

    it 'can' do
      # test what a user can do
      # More on `must_permit` and `wont_permit` later :-)
      something.must_permit user, [:new?, :create?, :edit?, :update?]
    end

    it 'can not' do
      # test what a user can't do
      something.wont_permit user, :destroy?
    end

    describe 'scope' do
      it 'includes something' do
        # test things about the user scope
      end
    end
  end

  describe 'admin' do
    let(:admin) { build :admin }
    # same stuff for an admin or other role
  end
end

This has been kind of a nice starting point, but I frequently deviate from this pattern if it makes sense or as the list of things they can or can not do gets longer and more complex.

Custom Assertions

How do we make assertions about a policy? Well, a policy is just a Ruby class… so all we have to do is instantiate the policy and call it’s instance methods. Pundit provides a nice class method .policy for instantiating a policy. It infers the name of the policy from the class of the given record and then instantiates the policy using the user and record passed in. So in order to test our policy, we could make assertions using the result of calling methods on the policy.

# ...
  test 'user can' do
    assert Pundit.policy(user, record).show?
  end

  # or spec

  it 'can' do
    Pundit.policy(user, record).show?.must_equal true
  end

But this isn’t going to give meaningful error messages and contains a lot of boilerplate code. To help make things clearer, lets write custom MiniTest assertions to help test our policy. I’ve defined these in test/helpers/pundit.rb and then required that file in test_helper.rb

module MiniTest
  module Assertions
    ##
    # Fails unless there is a Pundit policy for the user and record and permits
    # the action.
    # user: instance of User
    # record: instance or class of object being authorized
    # action: string or symbol of the action being authorized or array of
    #         strings/ symbols

    def assert_permit(user, record, actions)
      actions = Array(actions)

      actions.each do |action|
        msg = "User #{user.inspect} should be permitted to #{action} #{record}, but isn't permitted"
        assert Pundit.policy!(user, record).public_send(action), msg
      end
    end

    ##
    # Same as `assert_permit` except it fails if user IS permitted for the
    # record and action

    def refute_permit(user, record, actions)
      actions = Array(actions)

      actions.each do |action|
        msg = "User #{user.inspect} should NOT be permitted to #{action} #{record}, but is permitted"
        refute Pundit.policy!(user, record).public_send(action), msg
      end
    end
  end
end

This opens up the MiniTest::Assertions module and defines two newly minted assertions. Under the hood it uses Pundit.policy like we were before. I chose to use the ‘bang’ version, .policy!, so that if the policy is not yet defined, we get a meaningful error message. Otherwise we would simply get a nil class error. #public_send is used to dynamically call the given ‘action’ method on the policy. #public_send is used because I only want to test the public methods available in the policy, not any private helper stuff I might have defined.

We now have a much more descriptive error message for when our assertion fails. I used #.inspect with user in the error message so that you can see the attributes of the user when you are debugging a test… although if this is too much info you could play around with what makes most sense for you. Array() is used to convert whatever we pass into the ‘action’ parameter to an array, if possible; this way we can choose to pass in a single action or an array of actions.

With these new assertions, we can now use them like

test 'a user can' do
  assert_permit user, record, :show?
  # or
  assert_permit user, record, [:new?, :create?, :edit?, :update?]
  # or
  assert_permit user, Record, :new?
end

and then you would get a helpful error message like:

  User #<User id: nil, email: "test558484455@example.com", password_digest: "$2a$04$u0rOr5nwXzYHcydrVJZq.ONO5bKnZj2AoSIjE6Touw/...", role: 2, organization_id: 1> should be permitted to update? #<Something:0x007fc71ca58ff8>, but isn't permitted

But we don’t want to leave the MiniTest:Spec-ers without an expectation to hide these assertions in. Fortunately, it is wonderfully easy to turn an assertion into an expectation. At the bottom of test/helpers/pundit.rb we’ll add the following

module Minitest
  module Expectations
    ##
    # See `assert_permit`
    # Use like `record.must_permit user, action`

    infect_an_assertion :assert_permit, :must_permit

    ##
    # See `refute_permit`
    # Use like `record.wont_permit user, action`

    infect_an_assertion :refute_permit, :wont_permit
  end
end

and that’s it! We can now use our expectations in our tests:

it 'can' do
  something.must_permit user, :show?
  # or
  something.must_permit user, [:new?, :create?, :edit?, :update?]
  # or
  Something.must_permit user, :new?
end

Testing Scope

Testing scope is pretty straight forward. Pundit provides .policy_scope for retrieving records using the scope, so all we have to do is make sure that we only get the records we expect to get and not the others. For example:

describe 'scope' do
  attr_accessor :another_thing, :result, :thing
  let(:user) { create :user }

  before do
    @thing = create :thing, user: user
    @another_thing = create :another_thing
    @result = Pundit.policy_scope!(user, Thing)
  end

  it 'includes a thing' do
    result.must_include thing
  end

  it 'wont include another thing' do
    result.wont_include another_thing
  end
end

The End!

This pretty much sums up how I test my Pundit policies. I’ll leave you with a complete copy of my test/helpers/pundit.rb. Happy testing!

module MiniTest
  module Assertions
    ##
    # Fails unless there is a Pundit policy for the user and record and permits
    # the action.
    # user: instance of User
    # record: instance or class of object being authorized
    # action: string or symbol of the action being authorized or array of
    #         strings/ symbols

    def assert_permit(user, record, actions)
      actions = Array(actions)

      actions.each do |action|
        msg = "User #{user.inspect} should be permitted to #{action} #{record}, but isn't permitted"
        assert Pundit.policy!(user, record).public_send(action), msg
      end
    end

    ##
    # Same as `assert_permit` except it fails if user IS permitted for the
    # record and action

    def refute_permit(user, record, actions)
      actions = Array(actions)

      actions.each do |action|
        msg = "User #{user.inspect} should NOT be permitted to #{action} #{record}, but is permitted"
        refute Pundit.policy!(user, record).public_send(action), msg
      end
    end
  end
end

module MiniTest
  module Expectations
    ##
    # See `assert_permit`
    # Use like `record.must_permit user, action`

    infect_an_assertion :assert_permit, :must_permit

    ##
    # See `refute_permit`
    # Use like `record.wont_permit user, action`

    infect_an_assertion :refute_permit, :wont_permit
  end
end