Writing Tests First with Comments
5 minute read
| F | M | T | W | T | F |
|---|---|---|---|---|---|
| Intro session | Slack check-in | Refinement | Sharing stories | ||
| Slack the challenge | Refinement prep |
Intro Session
Flow
What stance should I be in? Where to focus? Any ways the content will guide me astray?
Immediately after
Post the following to Slack:
Today's challenge:
*Notice*: when you are about to write code or debug something.
*Act*: first describe your coding intent using comments in the structure of a 4-part test.
Gotchas:
* Remember not to write any code in the test! Just comments.
* Commit as soon as you have the test. Then do a second commit to do your coding, however you normally would.
*Practice tag:* `[intent]`
1. Name the test based on your intent.
2. Create the test using the standard template.
3. Write the outcome. What would the user expect?
* Use comments in natural language - not code!
4. Write the initial state, also as comments. What is the starting condition?
5. Write the action that your code will do, still as comments. Conceptually, how do you get from the starting condition to the outcome?
6. Commit as `[intent]`.
https://learn.digdeeproots.com/vsd/milestone-1/module-1/1/
Slack check-in
What one thing should I remember to do in Slack on day 2?
Refinement Prep
Copy this into the parallel writing doc.
Write Comments First - Cohort 1
| Your name | How many [intent] commits? | What is the difference between the comments you wrote in the test and the code you wrote in the product? | Which of the 3 sections was most difficult to fill in and why? |
|---|---|---|---|
| Your name | Sometimes recipes need variations. What situations made you vary the recipe slightly? | When did you stray from a literal interpretation of the recipe? Why? | What situations made the recipe not apply? |
|---|---|---|---|
- What are other situations in which it would be useful to record one piece of intent at a time before starting to try to accomplish that intent?
- .
- .
- .
- .
- .
Refinement
It is very common to have near-0 participation in the practice at this point. Students aren’t used to having to apply techniques from training, they struggle to see when to apply these techniques (since they are new to them), and they will often have “two odd days with no coding”. None of these prevent the course, but they are sufficient to cause students to fail to apply the concepts.
So we need to gently help them apply this one behavior, this one time.
The first thing to do in the session is to assess: do I have a typical group which fails to apply the behavior, or am I in the unusual case where most people are applying it. Ask for a show of hands “Who made an [intent] commit at least once?”, then “who wasn’t able to apply it?”. Success is if at least 80% of the group attempted the behavior at least 2 times, preferably a lot more.
Pick the appropriate refinement call based on the answer.
Refinement if no one practiced
Ask for the reasons that people didn’t execute. Go around the raised hands to “who wasn’t able to apply it?” and cluster the answers.
You will probably see these clusters, and you may see others:
- My work doesn’t match this recipe, because X. (I don’t use source control, I don’t write code, there is no test framework for my language.)
- My work this week prevented it, because I was documenting/on a high-pri bug fix/in meetings/doing something else.
- I looked for the opportunity, and it simply never came up.
Pick one person in each cluster and work with them to do the recipe. They’ll drive + share; you navigate & request suggestions from the watchers.
- Adapt the recipe if needed for downlevel environments. Eg, if they write SQL, then show them how to convey intent as pseudo-tests in the same file as the SQL they are working on.
- If they don’t use source control, suggest they keep a log. Just record each time they did the recipe and what they were working on.
- If they don’t store their work in files, see if there is somewhere in the UI or in their task management software that they can record their intent. Eg, when workign on a data dashboard, place the intent verifications on the dash right next to the table/chart you are creating.
- Show how to use intention narrowing to assist a bug hunt. You are writing a test to expose the current behavior (pass with bug), then narrowing the inital state, reducing the scope of the action, and even refining the outcome to get more specific.
- Don’t let them get hung up on worries about test framework or language, but do help them start figuring that out. Because week 2 depends on it, though week 1 does not.
Refinement if practice happened
Go through the paralell writing exercise in the doc. For tables, parallel write one column at a time (make the headers white text until ready), the start a conversation about trends you see or interesting outliers. For bullet lists, get them to do questions and answers to each other and build a conversation tree.
Sharing stories
Check again if practice happened. If practice didn’t happen before refinement but now has, then celebrate that.
If practice still isn’t happening, then abort the story share and debug why. The course won’t be useful if the practice isn’t happening.
Ask people to share stories where the behavior was useful. Then ask them to share ones where it failed. Ask the room to see if they can suggest a way to make it succeed in those cases. You don’t need to solve everything - it’s OK to have behaviors work some of the time. Just help people see what causes failures & how to reduce some of them.