CODING_STYLE: provide better explanation why /* */ over // (#7647)

Let's provide a real reason why /* */ should be used for commenting,
rather than //, beyond mere taste.

(This ultimately simply codifies how I use // vs. /* */ comments, and I
think this is useful as an explanation and reason hence.)

diff --git a/CODING_STYLE b/CODING_STYLE
index 4119cfe..ae81812 100644 (file)
--- a/CODING_STYLE
+++ b/CODING_STYLE
@@ -1,9 +1,11 @@
 - 8ch indent, no tabs, except for files in man/ which are 2ch indent,
   and still no tabs
 
-- We prefer /* comments */ over // comments, please. This is not C++, after
-  all. (Yes we know that C99 supports both kinds of comments, but still,
-  please!)
+- We prefer /* comments */ over // comments in code you commit, please. This
+  way // comments are left for developers to use for local, temporary
+  commenting of code for debug purposes (i.e. uncommittable stuff), making such
+  comments easily discernable from explanatory, documenting code comments
+  (i.e. committable stuff).
 
 - Don't break code lines too eagerly. We do *not* force line breaks at
   80ch, all of today's screens should be much larger than that. But