Re: [boost] Official warnings policy?

Subject: Re: [boost] Official warnings policy?
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2009-11-05 12:07:36

> -----Original Message-----
> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]] On
Behalf Of
> Stewart, Robert
> Sent: Thursday, November 05, 2009 3:58 PM
> To: boost_at_[hidden]
> Subject: Re: [boost] Official warnings policy?
> 
> I don't have access -- I may never have signed up, but I don't have my
passwords with me
> to check -- so I'll comment here.  My rationale for each suggested change is
in
> parentheses.
> 
> Heading: "Managing Warnings"
> 
> (This heading fits the section better and describes the purpose a bit better.)
> 
> s/avoid warnings/eliminate or suppress warnings/
> 
> (We want to avoid them, but the purpose of this section is to eliminate them
or, if not
> possible, suppress them, isn't it?)
> 
> s/Some reasons are:/Reasons to eliminate or suppress warnings:/
> 
> 1. "To allow users, whose environment requires no warnings, to use Boost
code."
> 
> (Added commas for dependent clause and clarified "these conditions" as "no
warnings.")
> 
> 3. s/focussing/focusing/, s/writers/writer's/
> 
> (The former may be a British/American English difference.)
> 
> 4. "To improve portability by focusing developer attention on potentially
non-portable
> code."
> 
> (Don't want library user's attention drawn to the problems.)
> 
> 6. "To permit users to set high warning levels when using Boost libraries
without
> overwhelming them with a barrage of library warnings."
> 
> (Clarity.)
> 
> 7. (This bullet isn't a reason to eliminate/avoid warnings, but with the
addition of "or
> suppress" above, it fits.)
> 
> s/What to do/Actions:/
> 
> 1. (Rather than prose, use bullets or a table to list the settings for each
compiler:
> 
>     Compiler | Settings        | Comments
>    ------------------------------------------------------------
>     MSVC     | /W4 /Za         | disabling language extensions
>     GCC      | -Wall -pedantic |
> 
>    Using bjam, set warnings=all.
> 
> Notice the spelling correction for "pedantic.")
> 
> 2. "For each supported compiler, apply these steps for each warning found:"
> 
> (Highlight the need to check each supported compiler and highlight the need to
iterate over
> all warnings.)
> 
> 2. 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."
> 
> (Clarity. Focus on warning elimination rather than value of parameter names.)
> 
> 2. b. "If the warning cannot be eliminated, use whatever compiler-specific
mechanisms are
> available to suppress warnings constrained to the smallest scope possible so
as to avoid
> suppressing warnings in user code."
> 
> (Clarity. Note s/depricated/deprecated/ in first code block comment.)
> 
> "For MSVC, this involves pushing...to restore the original warning state:"
> 
> (s/involved/involves/ and explains what's restored.)
> 
> "If the warning is only for a specific compiler version, use this approach:"
> 
> (Reads better with the latter clause.)
> 
> 2. c. (Delete based upon rephrasing of 2.)
> 
> 2. 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."
> 
> (Clarity.)
> 
> Specific remedies should be added for the various warnings encountered, too.
> 
> Between 1. and 2., in the latter list, there should be a new bullet suggesting
to use
> warnings-as-errors.

Most of these correct or added.

Thanks

Paul

PS But it still needs much more input and checking, particular for gcc  (and
what about other compilers - no mention of acc, Darwin Borland...)