describe the preferred approach to silencing 'unused variable warnings' due to asserts.

llvm-svn: 118863

llvm/docs/CodingStandards.html

@@ -851,6 +851,38 @@ return 0;
 </pre>
 </div>
 
+<p>Another issue is that values used only by assertions will produce an "unused
+ value" warning when assertions are disabled.  For example, this code will warn:
+</p>
+
+<div class="doc_code">
+<pre>
+  unsigned Size = V.size(); 
+  assert(Size &gt; 42 &amp;&amp; "Vector smaller than it should be");
+
+  bool NewToSet = Myset.insert(Value);
+  assert(NewToSet &amp;&amp; "The value shouldn't be in the set yet");  
+</pre>
+</div>
+
+<p>These are two interesting different cases: in the first case, the call to 
+V.size() is only useful for the assert, and we don't want it executed when
+assertions are disabled.  Code like this should move the call into the assert
+itself.  In the second case, the side effects of the call must happen whether
+the assert is enabled or not.  In this case, the value should be cast to void
+to disable the warning.  To be specific, it is preferred to write the code
+like this:</p>
+
+<div class="doc_code">
+<pre>
+  assert(V.size() &gt; 42 &amp;&amp; "Vector smaller than it should be");
+
+  bool NewToSet = Myset.insert(Value); (void)NewToSet;
+  assert(NewToSet &amp;&amp; "The value shouldn't be in the set yet");  
+</pre>
+</div>
+
+
 </div>
 
 <!-- _______________________________________________________________________ -->