Sync darts (#867)

Author: tomasnorre

exercises/practice/darts/.docs/instructions.md

@@ -1,17 +1,31 @@
 # Instructions
 
-Write a function that returns the earned points in a single toss of a Darts game.
+Calculate the points scored in a single toss of a Darts game.
 
-[Darts](https://en.wikipedia.org/wiki/Darts) is a game where players
-throw darts to a [target](https://en.wikipedia.org/wiki/Darts#/media/File:Darts_in_a_dartboard.jpg).
+[Darts][darts] is a game where players throw darts at a [target][darts-target].
 
-In our particular instance of the game, the target rewards with 4 different amounts of points, depending on where the dart lands:
+In our particular instance of the game, the target rewards 4 different amounts of points, depending on where the dart lands:
 
-* If the dart lands outside the target, player earns no points (0 points).
-* If the dart lands in the outer circle of the target, player earns 1 point.
-* If the dart lands in the middle circle of the target, player earns 5 points.
-* If the dart lands in the inner circle of the target, player earns 10 points.
+![Our dart scoreboard with values from a complete miss to a bullseye](https://assets.exercism.org/images/exercises/darts/darts-scoreboard.svg)
 
-The outer circle has a radius of 10 units (This is equivalent to the total radius for the entire target), the middle circle a radius of 5 units, and the inner circle a radius of 1. Of course, they are all centered to the same point (That is, the circles are [concentric](https://mathworld.wolfram.com/ConcentricCircles.html)) defined by the coordinates (0, 0).
+- If the dart lands outside the target, player earns no points (0 points).
+- If the dart lands in the outer circle of the target, player earns 1 point.
+- If the dart lands in the middle circle of the target, player earns 5 points.
+- If the dart lands in the inner circle of the target, player earns 10 points.
 
-Write a function that given a point in the target (defined by its `real` cartesian coordinates `x` and `y`), returns the correct amount earned by a dart landing in that point.
+The outer circle has a radius of 10 units (this is equivalent to the total radius for the entire target), the middle circle a radius of 5 units, and the inner circle a radius of 1.
+Of course, they are all centered at the same point — that is, the circles are [concentric][] defined by the coordinates (0, 0).
+
+Given a point in the target (defined by its [Cartesian coordinates][cartesian-coordinates] `x` and `y`, where `x` and `y` are [real][real-numbers]), calculate the correct score earned by a dart landing at that point.
+
+## Credit
+
+The scoreboard image was created by [habere-et-dispertire][habere-et-dispertire] using [Inkscape][inkscape].
+
+[darts]: https://en.wikipedia.org/wiki/Darts
+[darts-target]: https://en.wikipedia.org/wiki/Darts#/media/File:Darts_in_a_dartboard.jpg
+[concentric]: https://mathworld.wolfram.com/ConcentricCircles.html
+[cartesian-coordinates]: https://www.mathsisfun.com/data/cartesian-coordinates.html
+[real-numbers]: https://www.mathsisfun.com/numbers/real-numbers.html
+[habere-et-dispertire]: https://exercism.org/profiles/habere-et-dispertire
+[inkscape]: https://en.wikipedia.org/wiki/Inkscape

exercises/practice/darts/.meta/config.json

@@ -13,5 +13,6 @@
       ".meta/example.php"
     ]
   },
-  "blurb": "Write a function that returns the earned points in a single toss of a Darts game"
+  "blurb": "Calculate the points scored in a single toss of a Darts game.",
+  "source": "Inspired by an exercise created by a professor Della Paolera in Argentina"
 }

exercises/practice/darts/.meta/example.php

@@ -1,52 +1,20 @@
 <?php
 
-/*
- * By adding type hints and enabling strict type checking, code can become
- * easier to read, self-documenting and reduce the number of potential bugs.
- * By default, type declarations are non-strict, which means they will attempt
- * to change the original type to match the type specified by the
- * type-declaration.
- *
- * In other words, if you pass a string to a function requiring a float,
- * it will attempt to convert the string value to a float.
- *
- * To enable strict mode, a single declare directive must be placed at the top
- * of the file.
- * This means that the strictness of typing is configured on a per-file basis.
- * This directive not only affects the type declarations of parameters, but also
- * a function's return type.
- *
- * For more info review the Concept on strict type checking in the PHP track
- * <link>.
- *
- * To disable strict typing, comment out the directive below.
- */
-
 declare(strict_types=1);
 
-class Darts
+function score(float $xAxis, float $yAxis): int
 {
-    public int $score = 0;
+    $location = $xAxis ** 2 + $yAxis ** 2;
 
-    public function __construct(float $xAxis, float $yAxis)
-    {
-        $this->score = $this->calculateScore($xAxis, $yAxis);
+    if ($location > 100) {
+        return 0;
     }
-
-    private function calculateScore(float $xAxis, float $yAxis): int
-    {
-        $location = $xAxis ** 2 + $yAxis ** 2;
-
-        if ($location > 100) {
-            return 0;
-        }
-        if ($location > 25) {
-            return 1;
-        }
-        if ($location > 1) {
-            return 5;
-        }
-
-        return 10;
+    if ($location > 25) {
+        return 1;
+    }
+    if ($location > 1) {
+        return 5;
     }
+
+    return 10;
 }

exercises/practice/darts/.meta/tests.toml

@@ -0,0 +1,49 @@
+# This is an auto-generated file.
+#
+# Regenerating this file via `configlet sync` will:
+# - Recreate every `description` key/value pair
+# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
+# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
+# - Preserve any other key/value pair
+#
+# As user-added comments (using the # character) will be removed when this file
+# is regenerated, comments can be added via a `comment` key.
+
+[9033f731-0a3a-4d9c-b1c0-34a1c8362afb]
+description = "Missed target"
+
+[4c9f6ff4-c489-45fd-be8a-1fcb08b4d0ba]
+description = "On the outer circle"
+
+[14378687-ee58-4c9b-a323-b089d5274be8]
+description = "On the middle circle"
+
+[849e2e63-85bd-4fed-bc3b-781ae962e2c9]
+description = "On the inner circle"
+
+[1c5ffd9f-ea66-462f-9f06-a1303de5a226]
+description = "Exactly on center"
+
+[b65abce3-a679-4550-8115-4b74bda06088]
+description = "Near the center"
+
+[66c29c1d-44f5-40cf-9927-e09a1305b399]
+description = "Just within the inner circle"
+
+[d1012f63-c97c-4394-b944-7beb3d0b141a]
+description = "Just outside the inner circle"
+
+[ab2b5666-b0b4-49c3-9b27-205e790ed945]
+description = "Just within the middle circle"
+
+[70f1424e-d690-4860-8caf-9740a52c0161]
+description = "Just outside the middle circle"
+
+[a7dbf8db-419c-4712-8a7f-67602b69b293]
+description = "Just within the outer circle"
+
+[e0f39315-9f9a-4546-96e4-a9475b885aa7]
+description = "Just outside the outer circle"
+
+[045d7d18-d863-4229-818e-b50828c75d19]
+description = "Asymmetric position between the inner and middle circles"

exercises/practice/darts/Darts.php

@@ -24,12 +24,7 @@
 
 declare(strict_types=1);
 
-class Darts
+function score(float $xAxis, float $yAxis): int
 {
-    public int $score = 0;
-
-    public function __construct(float $xAxis, float $yAxis)
-    {
-        throw new BadFunctionCallException("Please implement the Darts class!");
-    }
+    throw new BadFunctionCallException("Please implement the __FUNCTION__ function!");
 }

exercises/practice/darts/DartsTest.php

@@ -1,27 +1,5 @@
 <?php
 
-/*
- * By adding type hints and enabling strict type checking, code can become
- * easier to read, self-documenting and reduce the number of potential bugs.
- * By default, type declarations are non-strict, which means they will attempt
- * to change the original type to match the type specified by the
- * type-declaration.
- *
- * In other words, if you pass a string to a function requiring a float,
- * it will attempt to convert the string value to a float.
- *
- * To enable strict mode, a single declare directive must be placed at the top
- * of the file.
- * This means that the strictness of typing is configured on a per-file basis.
- * This directive not only affects the type declarations of parameters, but also
- * a function's return type.
- *
- * For more info review the Concept on strict type checking in the PHP track
- * <link>.
- *
- * To disable strict typing, comment out the directive below.
- */
-
 declare(strict_types=1);
 
 class DartsTest extends PHPUnit\Framework\TestCase
@@ -31,81 +9,120 @@ public static function setUpBeforeClass(): void
         require_once 'Darts.php';
     }
 
+    /**
+     * uuid 9033f731-0a3a-4d9c-b1c0-34a1c8362afb
+     * @testdox Missed target
+     */
     public function testMissedTarget(): void
     {
-        $board = new Darts(-9, 9);
-        $this->assertEquals(0, $board->score);
+        $this->assertEquals(0, score(-9.0, 9.0));
     }
 
+    /**
+     * uuid 4c9f6ff4-c489-45fd-be8a-1fcb08b4d0ba
+     * @testdox On the outer circle
+     */
     public function testInOuterCircle(): void
     {
-        $board = new Darts(0, 10);
-        $this->assertEquals(1, $board->score);
+        $this->assertEquals(1, score(0.0, 10.0));
     }
 
+    /**
+     * uuid 14378687-ee58-4c9b-a323-b089d5274be8
+     * @testdox On the middle circle
+     */
     public function testInMiddleCircle(): void
     {
-        $board = new Darts(-5, 0);
-        $this->assertEquals(5, $board->score);
+        $this->assertEquals(5, score(-5.0, 0.0));
     }
 
+    /**
+     * uuid 849e2e63-85bd-4fed-bc3b-781ae962e2c9
+     * @testdox On the inner circle
+     */
     public function testInInnerCircle(): void
     {
-        $board = new Darts(0, -1);
-        $this->assertEquals(10, $board->score);
+        $this->assertEquals(10, score(0.0, -1.0));
     }
 
+    /**
+     * uuid 1c5ffd9f-ea66-462f-9f06-a1303de5a226
+     * @testdox Exactly on center
+     */
     public function testInCenter(): void
     {
-        $board = new Darts(0, 0);
-        $this->assertEquals(10, $board->score);
+        $this->assertEquals(10, score(0.0, 0.0));
     }
 
+    /**
+     * uuid b65abce3-a679-4550-8115-4b74bda06088
+     * @testdox Near the center
+     */
     public function testNearCenter(): void
     {
-        $board = new Darts(-0.1, -0.1);
-        $this->assertEquals(10, $board->score);
+        $this->assertEquals(10, score(-0.1, -0.1));
     }
 
+    /**
+     * uuid 66c29c1d-44f5-40cf-9927-e09a1305b399
+     * @testdox Just within the inner circle
+     */
     public function testJustInsideCenter(): void
     {
-        $board = new Darts(0.7, 0.7);
-        $this->assertEquals(10, $board->score);
+        $this->assertEquals(10, score(0.7, 0.7));
     }
 
+    /**
+     * uuid d1012f63-c97c-4394-b944-7beb3d0b141a
+     * @testdox Just outside the inner circle
+     */
     public function testJustOutsideCenter(): void
     {
-        $board = new Darts(0.8, -0.8);
-        $this->assertEquals(5, $board->score);
+        $this->assertEquals(5, score(0.8, -0.8));
     }
 
+    /**
+     * uuid ab2b5666-b0b4-49c3-9b27-205e790ed945
+     * @testdox Just within the middle circle
+     */
     public function testJustWithinMiddleCircle(): void
     {
-        $board = new Darts(-3.5, 3.5);
-        $this->assertEquals(5, $board->score);
+        $this->assertEquals(5, score(-3.5, 3.5));
     }
 
+    /**
+     * uuid 70f1424e-d690-4860-8caf-9740a52c0161
+     * @testdox Just outside the middle circle
+     */
     public function testJustOutsideMiddleCircle(): void
     {
-        $board = new Darts(-3.6, -3.6);
-        $this->assertEquals(1, $board->score);
+        $this->assertEquals(1, score(-3.6, -3.6));
     }
 
+    /**
+     * uuid a7dbf8db-419c-4712-8a7f-67602b69b293
+     * @testdox Just within the outer circle
+     */
     public function testJustInsideOuterCircle(): void
     {
-        $board = new Darts(-7.0, 7.0);
-        $this->assertEquals(1, $board->score);
+        $this->assertEquals(1, score(-7.0, 7.0));
     }
 
+    /**
+     * uuid e0f39315-9f9a-4546-96e4-a9475b885aa7
+     * @testdox Just outside the outer circle
+     */
     public function testJustOutsideOuterCircle(): void
     {
-        $board = new Darts(7.1, -7.1);
-        $this->assertEquals(0, $board->score);
+        $this->assertEquals(0, score(7.1, -7.1));
     }
 
+    /**
+     * uuid 045d7d18-d863-4229-818e-b50828c75d19
+     * @testdox Asymmetric position between the inner and middle circles
+     */
     public function testAsymmetricPositionBetweenInnerAndOuterCircles(): void
     {
-        $board = new Darts(0.5, -4);
-        $this->assertEquals(5, $board->score);
+        $this->assertEquals(5, score(0.5, -4));
     }
 }