From 8460f3a742af1e2222dc20061b7b314bd4e353a1 Mon Sep 17 00:00:00 2001 From: Geoff Hubbard Date: Tue, 25 Apr 2017 10:11:01 +0200 Subject: [PATCH 1/2] Add workload philosophy section. The Workload philosophy section gives some information about why an educational workload layout is preferable to a concise one liner. Link to the workload philosophy section from the first mention of workload. --- README.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3a2a391bd7..e0d9fa99d4 100644 --- a/README.md +++ b/README.md @@ -155,7 +155,7 @@ for the default template for everything except `workload`. `workload` generates the code for the body of a test, including the assertion and any setup required. The base class provides a variety of assertion and helper methods. Beyond that, you can implement any helper methods that you need -as private methods in your derived class. +as private methods in your derived class. See below for more information about [the intention of workload](#workload-philosophy) Below this class, implement a small loop that will generate all the test cases by reading the `canonical-data.json` file, and looping through the test cases. @@ -218,6 +218,23 @@ class ProblemNameTest < Minitest::Test end end ``` +### Workload philosophy. + +Within the test workload we want to prioritize educational value over expert comprehension and want to make sure that things are clear to people who may not be familiar with Minitest and even Ruby. + +Therefore a multi line workload is preferred. +An example from `anagram`: +```ruby +detector = Anagram.new('allergy') +anagrams = detector.match(["gallery", "ballerina", "regally", "clergy", "largely", "leading"]) +expected = ["gallery", "largely", "regally"] +assert_equal expected, anagrams.sort +``` + +This provides the information the student needs to derive the code to pass the test in a clear and consistent manner. +Intention revealing variable names are used to illustrate the purpose of the individual elements of what could otherwise be a one line assertion. The values used in `detector`,`anagrams` and `expected` will all vary by test. + + ## Pull Requests From 3bd8bf98a35a36fd08c4bef2a3f07bf9d61f9ede Mon Sep 17 00:00:00 2001 From: Geoff Hubbard Date: Tue, 25 Apr 2017 19:39:44 +0100 Subject: [PATCH 2/2] Reword based on feedback from @hilary. --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index e0d9fa99d4..40ecbb0111 100644 --- a/README.md +++ b/README.md @@ -220,10 +220,14 @@ end ``` ### Workload philosophy. -Within the test workload we want to prioritize educational value over expert comprehension and want to make sure that things are clear to people who may not be familiar with Minitest and even Ruby. +Prioritize educational value over expert comprehension and make sure that +things are clear to people who may not be familiar with Minitest and even Ruby. -Therefore a multi line workload is preferred. -An example from `anagram`: +Provide the information the student needs to derive the code to pass the test +in a clear and consistent manner. Illustrate the purpose of the individual +elements of the assertion by using meaningful variable names. + +Example output from the `workload` method: ```ruby detector = Anagram.new('allergy') anagrams = detector.match(["gallery", "ballerina", "regally", "clergy", "largely", "leading"]) @@ -231,10 +235,6 @@ expected = ["gallery", "largely", "regally"] assert_equal expected, anagrams.sort ``` -This provides the information the student needs to derive the code to pass the test in a clear and consistent manner. -Intention revealing variable names are used to illustrate the purpose of the individual elements of what could otherwise be a one line assertion. The values used in `detector`,`anagrams` and `expected` will all vary by test. - - ## Pull Requests