Changes between Version 15 and Version 16 of Guidelines/MaintenanceGuidelines

Timestamp:

Nov 5, 2009, 4:59:45 PM (13 years ago)

Author:

Paul A. Bristow

Comment:

Sugestion from Robert Stewart

Guidelines/MaintenanceGuidelines

@@ -539 +539 @@
 
 -----------------------------------------------------------------------------------------------
-== Warnings from Compilers (and other tools) - Code-Round, Suppress Warnings, or Document. == #warnings
+== Managing Warnings from Compilers (and other tools) == #warnings
+
+=== Avoid warnings, Eliminate warning, Suppress Warnings, or Document. ===
 
 Boost aims to avoid warnings messages as far as is reasonably practicable,
@@ -545 +547 @@
 avoiding vendor specific extensions if possible.
 
-'''Some reasons are:'''
-
-1  To allow users whose environment enforces these conditions to use Boost code.
+'''Reasons to eliminate or suppress warnings:'''
+
+1  To allow users, whose environment requires no warnings, to use Boost code.
 
 2  To avoid the nuisance, perhaps overwhelming, of spurious warning messages.
 
-3  To improve code quality by focussing library writers attention on potential problems.
-
-4  To improve portability by drawing attention to potentially non-portable code.
+3  To improve code quality by focusing library writers' attention on potential problems.
+
+4  To improve portability by focusing developer attention on potentially non-portable code.
 
 5  To improve compliance with the C++ Standard.
 
-6  To make it possible for users to enable high warning levels compiling their own code
-without being confused by a barrage of warnings from library code.
+6  To permit users to set high warning levels when using Boost libraries without being overwhelmed with a barrage of library warnings.
 
 7  To document that warnings have been considered by the library author or maintainer
@@ -575 +576 @@
 For GCC this means -Wall -pendantic  
 
-Using bjam add warnings=all to the invocation line.
+but you might consider adding specific warnings that are to be suppressed, for example:
+
+-pedantic -Wall -Wno-long-long -Wno-unused-value
+
+but this is a global setting, so you need to document that these warning must be suppressed by users of this module.  This may be acceptable if they are building a library of entirely Boost modules.
+
+Using bjam add warnings=all to the invocation command line.
 
 Putting options in jam files allows setting to be made for one or more specified compiler(s).
@@ -604 +611 @@
 }}}
 
+Using warning-as-errors will make it hard to miss warnings.
+  Microsoft command line option /WX,
+  gcc option -warning-as-errors
+
 2  Consider each warning and
 
-a  Rewrite the C++ code to avoid the error.  For example, a static_cast makes it clear that
-the warned-about potential loss of accuracy has been considered but is not believed to be possible or significant.
-
-Or placing /* comment */ around an unused variable name, allows the name still to be useful documentation.
-
-b  Use the compiler specific mechanism to supress the warning message, but try hard to ensure that this is as local
+a  Rewrite the code to avoid the warning, if possible. For example, adding a static_cast will indicate that any warning about loss of accuracy has been judged not possible or significant. Remove or comment out parameters to avoid warnings about unused parameters. Placing /* comment */ around an unused variable name, allows the name still to be useful documentation.
+
+b  Use the compiler specific mechanism to suppress the warning message, but try hard to ensure that this is as local
 to the package as possible so that users can still get warnings from *their code*.
 
@@ -620 +628 @@
 #if defined(_MSC_VER)
 #pragma warning(push) // Save warning settings.
-#pragma warning(disable : 4996) // disable deprecated localtime/gmtime warning.
+#pragma warning(disable : 4996) // Disable deprecated localtime/gmtime warning.
 #endif 
 
@@ -631 +639 @@
 }}}
 
-
-If the warning is only for a specific compiler version
-
+If the warning is only for a specific compiler version, us this approach:
 
 {{{
@@ -648 +654 @@
 }}}
 
-c  Repeat this process with other compilers and use their specific supression methods.
-
-d  Document the code and the associated documentation, and build tools like bjam to say that it is not possible
-to use some pedantic-ness level for this module, and why.
-
-
-
-
-
-
-
+c  Repeat this process with other compilers and use their specific suppression methods.
+
+d  If a warning cannot be eliminated or suppressed, explain why in the code and the documentation.  If appropriate, document in build files, as well.  Consider indicating the highest warning level possible or compiler-specific settings that will provide a warning-free build.
+
+
+
+
+