Re: [boost] Official warnings policy?

Subject: Re: [boost] Official warnings policy?
From: Stewart, Robert (Robert.Stewart_at_[hidden])
Date: 2009-11-05 10:58:28

Paul A. Bristow wrote:
> Beman Dawes wrote:
> >
> > One possible approach would be to create a wiki page that describes:
> >
> > * A first cut at a Boost policy on warnings.
> >
> > * For the current release of the critical compilers, what compiler
> > switches apply. "Critical compilers" are GCC, VC++, for now.
> >
> > * How a developer using bjam can run local tests with those
> > switches.
>
> Since I've been a moaned about warning, I've had a stab at this at
>
> https://svn.boost.org/trac/boost/wiki/Guidelines/MaintenanceGuidelines

Thanks Paul.

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.

_____
Rob Stewart                           robert.stewart_at_[hidden]
Software Engineer, Core Software      using std::disclaimer;
Susquehanna International Group, LLP  http://www.sig.com

IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.