diff --git a/handy.h b/handy.h
index 76454732aa9e..7e9dfc51083b 100644
--- a/handy.h
+++ b/handy.h
@@ -349,8 +349,8 @@ don't, so that you can portably take advantage of this C99 feature.
  *  3) shifting by 1, yielding   1111111...110
  *  4) adding the final bit yielding all 1's */
 #define nBIT_MASK(n)                                                        \
-            (((n) == 0) ? 0 : (((UINTMAX_C(1) << ((n) - 1)) - 1) << 1) | 1)
-                            //  |_________________________|
+       (((n) == 0) ? 0 : (((UINTMAX_C(1) << ((n) - 1)) - 1) << 1) | 1)
+  /*                       |_________________________|                   */
 
 /* The largest unsigned number that will fit into n bits */
 #define nBIT_UMAX(n)  nBIT_MASK(n)
diff --git a/pod/perlhacktips.pod b/pod/perlhacktips.pod
index 45ea2b635b18..e3f04418f6bb 100644
--- a/pod/perlhacktips.pod
+++ b/pod/perlhacktips.pod
@@ -230,7 +230,8 @@ changing to the C99 approach.
 C<//> comments
 
 All compilers we tested support their use. Not all humans we tested
-support their use.
+support their use.  These should be avoided in header files, as there is
+CPAN code that breaks if it encounters these.
 
 =item *