Show, Don’t Tell

There is a famous quote from Linus Torvalds from some time ago - “Talk is cheap. Show me the code”. With agentic engineering actually code has become rather cheap, but the agent doesn’t always understand what code you want - so it can still be a better idea to “Show me the code”. In this learning hour we go through a pattern for this kind of agentic prompting - “Show, Don’t tell”. This pattern is fairly similar to the Show the agent, let it repeat augmented coding pattern, except we prefer to use the code commit history as a reference rather than a markdown file.

Learning Goals

• Use a concrete code example (show, don’t tell) to guide a coding agent in propagating a pattern across a codebase.
• Produce your own example, then show the result to the agent as the pattern to follow.
• Identify when to use this agentic prompting technique - when it’s more accurate to explain what you want with a code example than with words.

Prerequisites

The learners should already be able to spot unit test smells such as a poorly written assertion and/or too many ‘Act’ steps.

Session Outline

• 5 min connect: What do you do when the agent doesn’t write the code you want it to?
• 10 min concept: Show Don’t Tell
• 10 min concept: Demo - improve assertion
• 10 min concrete: Follow the example in the previous commit
• 15 min concrete: Create an example to follow
• 5 min conclusions: When should you use this

Connect

Ask - “What do you do when the agent doesn’t write the code you want it to?” You are hoping they will talk about various strategies, including giving it an example.

This is an Open Question connect.

Concept

Ideally tell a story from your experience about a time when you used this prompting pattern. An example where your agent failed when you told it what to do in words, but then succeeded when you used this pattern:

• make one example of what you want (possibly by hand-coding)
• Make a commit (or short series of commits) with only that change
• Ask it to look at the example and find other, similar places in the code
• Ask it to apply this change in only those other places

If you don’t have a concrete code example you can talk about, explain the pattern in general terms.

Demo

Show how this works on a straightforward code example. For example, a series of test cases with poor assertions. Fix the first one by hand, commit, then prompt the agent to do it to all the other tests. Don’t use the same code as the upcoming exercise, but something similar.

Concrete Practice 1 - Use an existing example

The exercise repo Show Don’t tell contains both exercises. The first one is more straightforward, look at the “OrderTotalTest”.

Sample prompt:

We used a custom matcher in DiscountOnFirstLine_TotalAndLineValues
Are there other tests in the same file that can use this matcher?

That prompt might need adjusting for the specific test name in the language you are using.

The outcome you are hoping for is that the ai tool will update all the tests in that file with the same pattern.

Concrete Practice 2 - Create an example, apply it appropriately

The second exercise uses the OrderBookLifeCycleTest. The first test has some code smells. First ask people to name the smells, then split into pairs to fix the problem, then use the prompting pattern to fix the other relevant tests.

Exercise instructions:

• Improve the design of the first test case by splitting it into two test cases
• Commit with a good message
• Ask the AI tool to look at the previous commit and identify other places you could do the same design improvement.
• Ask the AI tool to update the other appropriate test cases.

The outcome you are hoping for is that the ai tool will update all the tests in that file with the same pattern, and not the others.

Conclusions

Ask “When should you use this - and when would this approach fail?” Hopefully people will explain that it works best when agents would otherwise misinterpret an instruction given in words. This approach can still fail if the agent identifies the wrong places to apply the example pattern.

This is a When should you use this activity.