From 23884518cbd0443b5e0d9c5ce4e6eb610b30fd08 Mon Sep 17 00:00:00 2001 From: Paul Robinson Date: Wed, 14 Nov 2018 13:43:19 +0000 Subject: [PATCH] Document how to comment an actual parameter. Differential Revision: https://reviews.llvm.org/D54446 llvm-svn: 346861 --- docs/CodingStandards.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/CodingStandards.rst b/docs/CodingStandards.rst index 92cad91a08e..88d8ff804d9 100644 --- a/docs/CodingStandards.rst +++ b/docs/CodingStandards.rst @@ -305,6 +305,21 @@ useful to use C style (``/* */``) comments however: #. When writing a source file that is used by a tool that only accepts C style comments. +#. When documenting the significance of constants used as actual parameters in + a call. This is most helpful for ``bool`` parameters, or passing ``0`` or + ``nullptr``. Typically you add the formal parameter name, which ought to be + meaningful. For example, it's not clear what the parameter means in this call: + + .. code-block:: c++ + + Object.emitName(nullptr); + + An in-line C-style comment makes the intent obvious: + + .. code-block:: c++ + + Object.emitName(/*Prefix=*/nullptr); + Commenting out large blocks of code is discouraged, but if you really have to do this (for documentation purposes or as a suggestion for debug printing), use ``#if 0`` and ``#endif``. These nest properly and are better behaved in general