140 add comments

1 files changed, 35 insertions, 0 deletions

diff --git a/challenge-140/jake/perl/ch-1.pl b/challenge-140/jake/perl/ch-1.pl
index 112b2e33b9..7e199720aa 100644
--- a/challenge-140/jake/perl/ch-1.pl
+++ b/challenge-140/jake/perl/ch-1.pl
@@ -30,6 +30,19 @@ my $result_decimal = $a_decimal + $b_decimal;
 my $result_binary = decimal_to_binary ( $result_decimal );
 print "$result_binary\n";
 
+###
+# convert decimals to binaries
+#
+# each n-th power of 2 in decimal translates to the n-th power of 10 in binary:
+# n=0: 1>1 | n=1: 2>10 | n=2: 4>100 and so on, we know the drill.
+# For conversion, we first determine the largest power contained in the decimal number.
+# Next, we subtract this power from our decimal and determine the largest power in this 'remainder'.
+# This is repeated until there is no remainder left.
+# For each n-th power of 2 we add a binary quantum to an accumulator.
+# At the end of our 'run for power' this accumulator is our binary equivalent to our decimal.
+###
+
+# container sub so main needs to pass only 1 argument
 sub decimal_to_binary {
     my ( $decimal ) = @_;
 
@@ -39,15 +52,24 @@ sub decimal_to_binary {
 sub _decimal_to_binary {
     my ( $power, $decimal_number, $binary_quantum ) = @_;
 
+    # special case of 0
     if ( $decimal_number == 0 ) {
         return 0;
     }
 
+    # any decimal or remainder hitting exactly an n-th power of 2 will eventually finish the run here
     if ( $decimal_number == 2**$power ) {
         $binary_quantum += 10**$power;
         return $binary_quantum; 
     }
 
+    # if a number will not finish at the previous step, we check if the number is between the current power or the next one.
+    # if it is, we know the largest power to 2 in this number is the current power, so we have to add this power to 10 to our binary quantum accumulator.
+    # we then take the remainder (what comes on top of the current power to 2) and investigate its powers.
+    # p.e. our decimal is 9.
+    # since 2^3 < 9 < 2^4, we add 10^3 to our binary quant.
+    # then we perform 9-2^3 = 1 to get the remainder which needs to be quantized itself.
+    # 1 is our remaining decimal, which we re-investigate starting again with power = 0.
     if ( $decimal_number > 2**$power && $decimal_number < 2**( $power +1 ) ) {
         $binary_quantum += 10**$power;
         $decimal_number -= 2**$power;
@@ -55,10 +77,22 @@ sub _decimal_to_binary {
         return _decimal_to_binary ( $power, $decimal_number, $binary_quantum );
     }
 
+    # this operation is needed whenever our decimal is larger than our current power to 2 and the next one.
     $power++;
     return _decimal_to_binary ( $power, $decimal_number, $binary_quantum );
 }
 
+###
+# convert binaries to decimals
+#
+# We investigate each digit of our binary number starting from the back.
+# Every digit represents the next power to 2, so we count the digits as we run towards the front of the binary.
+# For each digit we check if it's 1 or 0.
+# Whenever we hit a 1 we use the digit count as power to 2 and add the result to our accumulator.
+# Once we reach the beginning of our binary, we will have accumulated our decimal.
+###
+
+# container sub so main needs to pass only 1 argument
 sub binary_to_decimal {
     my ( $binary ) = @_;
 
@@ -68,6 +102,7 @@ sub binary_to_decimal {
 sub _binary_to_decimal {
     my ( $binary_number, $power, $acc, $tail ) = @_;
 
+    # once we reach the beginning of our binary the string will be empty, since in each iteration we chop the tail off of our binary
     return $acc if $binary_number eq '';
 
     $tail = chop ($binary_number);