Document internals (and bug!) of card_group_is_run

diff --git a/kub.c b/kub.c
index aec86bee557348ae318c7614bf8a7fa6dc6a9889..92cc533fdc74f6ae46c4e9879b9cb2a7928f3a09 100644 (file)
--- a/kub.c
+++ b/kub.c
@@ -86,18 +86,24 @@ static int card_group_is_run(card_group_t *card_group)
     int lowest = 14, highest = 0;
     color_t run_color;
 
-    if (card_group->num_cards > 13 || card_group->num_cards < 3)
+    /* By definition, a run must have at least 3 cards. Also, it's
+     * impossible for any group of cards with more than 13 cards to be
+     * a run, (there are only 13 unique numbers so a group with more
+     * than 13 cards must have some duplicates).
+     */
+    if (card_group->num_cards < 3 || card_group->num_cards > 13)
     {
        return 0;
     }
 
+    /* Loop through all cards in the group, ensuring that they are all
+     * the same color and finding the highest and lowest number in the
+     * group. */
     run_color = card_group->cards[i].color;
-
     for (i = 0; i < card_group->num_cards; i++)
     {
        if (card_group->cards[i].color != run_color)
            return 0;
-
        if (card_group->cards[i].number > highest)
        {
            highest = card_group->cards[i].number;
@@ -107,10 +113,31 @@ static int card_group_is_run(card_group_t *card_group)
            lowest = card_group->cards[i].number;
        }
     }
+
+    /* For a run, the difference between the highest and lowest cards
+     * will always be one less than the number of cards in the
+     * group. If not then we know it's not a run.
+     */
     if (highest - lowest != card_group->num_cards - 1)
     {
        return 0;
     }
+
+    /* XXX: There's a bug here. We're guessing that at this point
+     * anything we're looking at must be a run. This would be correct
+     * if there were no duplicate cards, but since there are
+     * duplicates this us quite broken. For example consider two
+     * sequences of entirely red cards:
+     *
+     * This is a run:   1, 2, 3, 4
+     * But this is not: 1, 3, 4, 4
+     *
+     * As currently written, this function will consider both of these
+     * groups to be a run. One possible fix is to throw away the
+     * highest - lowest heuristic and instead simply sort the cards up
+     * front and ensure the difference between each adjacent pair is
+     * exactly 1.
+     */
     return 1;
 }