From f416ee371acc9f33127470a0bba70ee59f27bb9c Mon Sep 17 00:00:00 2001 From: emilybache Date: Fri, 12 Oct 2012 16:17:59 +0200 Subject: [PATCH] Updated the README files to markdown, improved the instructions. --- GildedRose/GildedRoseRequirements.txt | 2 +- GildedRose/README | 54 --------------------------- GildedRose/README.md | 24 ++++++++++++ README | 9 ----- README.md | 13 +++++++ Tennis/README.md | 18 +++++++++ Yahtzee/{README => README.md} | 18 +++------ 7 files changed, 62 insertions(+), 76 deletions(-) delete mode 100644 GildedRose/README create mode 100644 GildedRose/README.md delete mode 100644 README create mode 100644 README.md create mode 100644 Tennis/README.md rename Yahtzee/{README => README.md} (90%) diff --git a/GildedRose/GildedRoseRequirements.txt b/GildedRose/GildedRoseRequirements.txt index 80b6165f..a8f47b48 100644 --- a/GildedRose/GildedRoseRequirements.txt +++ b/GildedRose/GildedRoseRequirements.txt @@ -21,6 +21,6 @@ We have recently signed a supplier of conjured items. This requires an update to - "Conjured" items degrade in Quality twice as fast as normal items -Feel free to make any changes to the UpdateQuality method and add any new code as long as everything still works correctly. +Feel free to make any changes to the UpdateQuality method and add any new code as long as everything still works correctly. However, do not alter the Item class or Items property as those belong to the goblin in the corner who will insta-rage and one-shot you as he doesn't believe in shared code ownership (you can make the UpdateQuality method and Items property static if you like, we'll cover for you). Just for clarification, an item can never have its Quality increase above 50, however "Sulfuras" is a legendary item and as such its Quality is 80 and it never alters. \ No newline at end of file diff --git a/GildedRose/README b/GildedRose/README deleted file mode 100644 index 3ba18362..00000000 --- a/GildedRose/README +++ /dev/null @@ -1,54 +0,0 @@ -This Kata was originally created by Terry Hughes (http://twitter.com/#!/TerryHughes). It is already on GitHub as "GildedRose", a sample project for C#. I could have forked it again, but I thought other language users might not want to download a whole C# project environment. In this repository are starting code samples for Java, Python, Ruby, Smalltalk, C# and C++. - -See also http://iamnotmyself.com/2011/02/13/refactor-this-the-gilded-rose-kata/ - -==================== -How to use this Kata -==================== - -The simplest way is to just clone the code and start hacking away improving the design. You'll want to look at the "Gilded Rose Background Reading" (below) which explains what the code is for. I strongly advise you that you'll also need some tests if you want to make sure you don't break the code while you refactor. - -You could write some unit tests yourself, using the Kata Background Reading (below) to identify suitable test cases. I've provided a failing unit test in a popular test framework as a starting point for most languages. - -Alternatively, use the "Text-Based" tests provided in this repository. (Read more about that in the next section) - -Whichever testing approach you choose, the idea of the exercise is to do some deliberate practice, and improve your Refactoring skills. The idea is not to re-write the code from scratch, but rather to practice taking small steps, running the tests often, and incrementally improving the design. - -================== -Text-Based Testing -================== - -This is a testing approach which is very useful when refactoring legacy code. The basic idea is to create tests that use the text which the code produces. Before you change the code, you run it, and save the output as a "Golden Copy". Then after you change the code, you run it again, and compare the output against the Golden Copy. Any differences, and the test fails. - -It's basically the same idea as "assertEquals(expected, actual)" in a unit test, except the text you are comparing is typically much longer, and the "expected" value is saved from actual output, rather than being defined in advance. - -Typically a piece of legacy code may not produce suitable textual output from the start, so you may need to modify it before you can write your first text-based test. That could involve inserting log statements into the code, or just writing a "main" method that executes the code and prints out what the result is afterwards. It's this latter approach we are using here to test GildedRose. - -The Text-Based tests in this repository are designed to be used with the tool "TextTest" (http://texttest.org). This tool helps you to organize and run text-based tests. There is more information in the README file in the "texttests" subdirectory. - -=================================== -Gilded Rose Kata Background Reading -=================================== - -Hi and welcome to team Gilded Rose. As you know, we are a small inn with a prime location in a prominent city ran by a friendly innkeeper named Allison. We also buy and sell only the finest goods. Unfortunately, our goods are constantly degrading in quality as they approach their sell by date. We have a system in place that updates our inventory for us. It was developed by a no-nonsense type named Leeroy, who has moved on to new adventures. Your task is to add the new feature to our system so that we can begin selling a new category of items. First an introduction to our system: - - - All items have a SellIn value which denotes the number of days we have to sell the item - - All items have a Quality value which denotes how valuable the item is - - At the end of each day our system lowers both values for every item - -Pretty simple, right? Well this is where it gets interesting: - - - Once the sell by date has passed, Quality degrades twice as fast - - The Quality of an item is never negative - - "Aged Brie" actually increases in Quality the older it gets - - The Quality of an item is never more than 50 - - "Sulfuras", being a legendary item, never has to be sold or decreases in Quality - - "Backstage passes", like aged brie, increases in Quality as it's SellIn value approaches; Quality increases by 2 when there are 10 days or less and by 3 when there are 5 days or less but Quality drops to 0 after the concert - -We have recently signed a supplier of conjured items. This requires an update to our system: - - - "Conjured" items degrade in Quality twice as fast as normal items - -Feel free to make any changes to the UpdateQuality method and add any new code as long as everything still works correctly. However, do not alter the Item class or Items property as those belong to the goblin in the corner who will insta-rage and one-shot you as he doesn't believe in shared code ownership (you can make the UpdateQuality method and Items property static if you like, we'll cover for you). - -Just for clarification, an item can never have its Quality increase above 50, however "Sulfuras" is a legendary item and as such its Quality is 80 and it never alters. \ No newline at end of file diff --git a/GildedRose/README.md b/GildedRose/README.md new file mode 100644 index 00000000..1672283e --- /dev/null +++ b/GildedRose/README.md @@ -0,0 +1,24 @@ +This Kata was originally created by Terry Hughes (http://twitter.com/#!/TerryHughes). It is already on GitHub [here](https://github.com/NotMyself/GildedRose). I could have forked it again, but I thought other language users might not want to download a whole C# project environment. In this repository are starting code samples for Java, Python, Ruby, Smalltalk, C#, C and C++. + +See also http://iamnotmyself.com/2011/02/13/refactor-this-the-gilded-rose-kata/ + +## How to use this Kata + +The simplest way is to just clone the code and start hacking away improving the design. You'll want to look at the ["Gilded Rose Requirements"](https://github.com/emilybache/Refactoring-Katas/blob/master/GildedRose/GildedRoseRequirements.txt) which explains what the code is for. I strongly advise you that you'll also need some tests if you want to make sure you don't break the code while you refactor. + +You could write some unit tests yourself, using the requirements to identify suitable test cases. I've provided a failing unit test in a popular test framework as a starting point for most languages. + +Alternatively, use the "Text-Based" tests provided in this repository. (Read more about that in the next section) + +Whichever testing approach you choose, the idea of the exercise is to do some deliberate practice, and improve your Refactoring skills. The idea is not to re-write the code from scratch, but rather to practice taking small steps, running the tests often, and incrementally improving the design. + +## Text-Based Testing + +This is a testing approach which is very useful when refactoring legacy code. The basic idea is to create tests that use the text which the code produces. Before you change the code, you run it, and save the output as a "Golden Copy". Then after you change the code, you run it again, and compare the output against the Golden Copy. Any differences, and the test fails. + +It's basically the same idea as "assertEquals(expected, actual)" in a unit test, except the text you are comparing is typically much longer, and the "expected" value is saved from actual output, rather than being defined in advance. + +Typically a piece of legacy code may not produce suitable textual output from the start, so you may need to modify it before you can write your first text-based test. That could involve inserting log statements into the code, or just writing a "main" method that executes the code and prints out what the result is afterwards. It's this latter approach we are using here to test GildedRose. + +The Text-Based tests in this repository are designed to be used with the tool "TextTest" (http://texttest.org). This tool helps you to organize and run text-based tests. There is more information in the README file in the "texttests" subdirectory. + diff --git a/README b/README deleted file mode 100644 index f2fc971c..00000000 --- a/README +++ /dev/null @@ -1,9 +0,0 @@ -Can you refactor? In really small steps? Can you turn some, frankly, ugly code into a paradigm of elegant, readable, extensible design? - -This is a collection of starting files for when practicing refactoring. - -Contents so far: - -Tennis Kata in Java, Python and C++. -Gilded Rose Kata in C++, C#, Java, Python and Ruby. (a C# version together with a starting project is already available on github) -Yahtzee Kata in C#, Java and Python (the C# and Java versions are also available in Jon Jagger's Cyberdojo) \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 00000000..18fc3dee --- /dev/null +++ b/README.md @@ -0,0 +1,13 @@ +# Refactoring Katas + +Can you refactor? In really small steps? Can you turn some, frankly, ugly code into a paradigm of elegant, readable, extensible design? + +This is a collection of starting files for when practicing refactoring. + +Contents so far: + +- Tennis Kata in Java, Python and C++. +- Gilded Rose Kata in C++, C#, Java, Python, Smalltalk, C and Ruby. (a C# version together with a starting project is already available on github [here](https://github.com/NotMyself/GildedRose)) +- Yahtzee Kata in C#, Java, C++ and Python (the C#, C++ and Java versions are also available in Jon Jagger's Cyberdojo, see [his blog post](http://jonjagger.blogspot.co.uk/2012/05/yahtzee-cyber-dojo-refactoring-in-java.html)) + +For more information about these and other katas, you may be interested in my book [The Coding Dojo Handbook](http://leanpub.com/codingdojohandbook) \ No newline at end of file diff --git a/Tennis/README.md b/Tennis/README.md new file mode 100644 index 00000000..76aed18c --- /dev/null +++ b/Tennis/README.md @@ -0,0 +1,18 @@ +# Tennis Refactoring Kata + +There are three versions of this refactoring kata, each with their own design smells and challenges. Two have been written by junior programmers with a weak grasp of how to solve the problem. The third is by an evil genius who values compactness above all else. The test suite provided is fairly comprehensive, and fast to run. You should not need to change the tests, only run them often as you refactor. + +## Tennis Kata + +Tennis has a rather quirky scoring system, and to newcomers it can be a little difficult to keep track of. The tennis society has contracted you to build a scoreboard to display the current score during tennis games. + +Your task is to write a “TennisGame” class containing the logic which outputs the correct score as a string for display on the scoreboard. When a player scores a point, it triggers a method to be called on your class letting you know who scored the point. Later, you will get a call “currentScore()” from the scoreboard asking what it should display. This method should return a string with the current score. + +You can read more about Tennis scores [here](http://en.wikipedia.org/wiki/Tennis#Scoring) which is summarized below: + +1. A game is won by the first player to have won at least four points in total and at least two points more than the opponent. +2. The running score of each game is described in a manner peculiar to tennis: scores from zero to three points are described as "love", "fifteen", "thirty", and "forty" respectively. +3. If at least three points have been scored by each player, and the scores are equal, the score is "deuce". +4. If at least three points have been scored by each side and a player has one more point than his opponent, the score of the game is "advantage" for the player in the lead. + +You need only report the score for the current game. Sets and Matches are out of scope. diff --git a/Yahtzee/README b/Yahtzee/README.md similarity index 90% rename from Yahtzee/README rename to Yahtzee/README.md index c6a65a1b..e861ff50 100644 --- a/Yahtzee/README +++ b/Yahtzee/README.md @@ -1,19 +1,12 @@ -======================== -Yahtzee Refactoring Kata -======================== +# Yahtzee Refactoring Kata -This Refactoring Kata was designed by Jon Jagger and is available in his Cyber-Dojo on these urls: - -C#: http://cyber-dojo.com/diff/show/E4466E24B2?avatar=elephant&tag=26 -Java: http://cyber-dojo.com/diff/show/3D5589AA49?avatar=panda&tag=1 +This Refactoring Kata was designed by Jon Jagger and is available in his Cyber-Dojo. See [his blog post](http://jonjagger.blogspot.co.uk/2012/05/yahtzee-cyber-dojo-refactoring-in-java.html) The other language translations have been contributed by: Python: Emily Bache -============= -Yahtzee rules -============= +## Kata: Yahtzee rules The game of yahtzee is a simple dice game. Each player rolls five six-sided dice. They can re-roll some or all @@ -46,8 +39,9 @@ The game is NOT played by letting the computer choose the highest scoring category for a given roll. -Yahzee Categories and Scoring Rules -=================================== +## Kata: Yahzee Categories and Scoring Rules + +_Note these rules differ from the original (copyrighted) rules_ Chance: The player scores the sum of all dice,