Comments.

2022/day1.py

@@ -5,6 +5,8 @@ from pathlib import Path
 with open(Path(__file__).parent.joinpath("inputs", "day1.txt")) as fp:
     lines = fp.readlines()
 
+# we store the list of calories for each elf in values, and we use the last element
+# of values to accumulate
 values: list[int] = [0]
 for line in lines:
     if not line.strip():

2022/day2.py

@@ -2,6 +2,8 @@
 
 from pathlib import Path
 
+# we read the lines in a Nx2 in array with value 0/1/2 instead of A/B/C or X/Y/Z for
+# easier manipulation
 with open(Path(__file__).parent.joinpath("inputs", "day2.txt")) as fp:
     values = [
         (ord(row[0]) - ord("A"), ord(row[2]) - ord("X")) for row in fp.readlines()
@@ -9,10 +11,17 @@ with open(Path(__file__).parent.joinpath("inputs", "day2.txt")) as fp:
 
 
 def score_1(ux: int, vx: int) -> int:
-    return 1 + vx + ((1 - ((ux - vx) % 3)) % 3) * 3
+    # explanation:
+    # - (1 + vx) is just the score of the shape
+    # - ((1 - (ux - vx)) % 3) gives 0 for loss, 1 for draw and 2 for win, that we
+    #   can multiply with 3 to get the outcome score
+    return (1 + vx) + ((1 - (ux - vx)) % 3) * 3
 
 
 def score_2(ux: int, vx: int) -> int:
+    # explanation:
+    # - (ux + vx - 1) % 3 gives the target shape (0, 1, 2), we add one to get the score
+    # - vx * 3 is simply the outcome score
     return (ux + vx - 1) % 3 + 1 + vx * 3