From 59e4d18e9dd1677abc2461f1e0c9abe6c4f83742 Mon Sep 17 00:00:00 2001
From: Steve Hancock <perltidy@users.sourceforge.net>
Date: Tue, 5 Jan 2021 07:10:15 -0800
Subject: [PATCH] update comments

---
 lib/Perl/Tidy/VerticalAligner.pm | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/lib/Perl/Tidy/VerticalAligner.pm b/lib/Perl/Tidy/VerticalAligner.pm
index 318f1391..e1db520d 100644
--- a/lib/Perl/Tidy/VerticalAligner.pm
+++ b/lib/Perl/Tidy/VerticalAligner.pm
@@ -4220,12 +4220,29 @@ sub is_good_side_comment_column {
 
     # RULE2: Forget a side comment after a short line difference,
     # where 'short line difference' is computed from a formula.
+    # Using a smooth formula helps minimize sudden large changes.
     my $line_diff = $line_number - $self->[_last_side_comment_line_number_];
     my $alev_diff = abs( $level - $self->[_last_side_comment_level_] );
 
-    # TAIL-WAG-DOG factor
+    # '$num5' is the number of comments in the first 5 lines after the first
+    # comment.  It is needed to keep a compact group of side comments from
+    # being influenced by a more distant side comment.
     $num5 = 1 unless ($num5);
 
+    # Some values:
+
+    #        $adiff  $num5   $short_diff
+    #        0       *       12
+    #        1       1       6
+    #        1       2       4
+    #        1       3       3
+    #        1       4       2
+    #        2       1       4
+    #        2       2       2
+    #        2       3       1
+    #        3       1       3
+    #        3       2       1
+
     my $short_diff = SC_LONG_LINE_DIFF / ( 1 + $alev_diff * $num5 );
 
     goto FORGET
-- 
2.39.5