Recommendations for enabling more compiler checks

[springmeyer]

Compilers enable by default, a set of warnings they will emit on dodgy or less-than-ideal code. These defaults:

• a. change over time
• b. vary between compiler versions
• c. do not include some of the most valuable warnings that might help prevent bugs

This issue is designed to focus on the problem of c from the perspective of the latest clang++ 4.x versions.

Enabling more warnings than compilers do by default can be an important way of catching bugs early. For example integer truncation bugs can often be detected by enabling -Wconversion, which is not on by default.

Enabling more warnings is very difficult to do after a project is big (e.g. https://github.com/Project-OSRM/osrm-backend/pull/4495 and https://github.com/mapnik/mapnik/issues/2907 and https://github.com/mapnik/mapnik/issues/3204). It is best not to wait and rather to start a project with aggressive warnings from the beginning.

So, the question then becomes: what is a good set of aggressive warnings to enable at the start of a project (or to try to integrate into existing projects)?

In particular:

1) 🍇 Which flags we should always enable for all code no matter what?

2) 🍊 What additional flags may be very useful in some scenarios/some code bases?

3) 🍏 For small projects where it is feasible, can we actually start with clang++s -Weverything? This, when feasible, might be ideal. How to do it?

4) 🍎 What compiler specific flags should we recommend (that only currently work for clang++ or g++)?

[springmeyer]

My proposal for 🍇 is:

• -Werror - turn warnings into errors so that we deal with them, rather than letting them pile up. And so that we see them on CI systems that might have different compilers. This should be on by default and able to be disabled by developers than need to bypass it for fast iteration.
• -Wall - Enables a big group of common warnings - see https://clang.llvm.org/docs/DiagnosticsReference.html#wall
• -Wextra - Enables key warnings like -Wunused-parameter and -Wsign-compare - see https://clang.llvm.org/docs/DiagnosticsReference.html#wextra
• -Wconversion - Enables key ones like -Wshorten-64-to-32 - see https://clang.llvm.org/docs/DiagnosticsReference.html#wconversion for others
• -Wunreachable-code - https://clang.llvm.org/docs/DiagnosticsReference.html#wunreachable-code
• -Wuninitialized - https://clang.llvm.org/docs/DiagnosticsReference.html#wuninitialized
• -pedantic-errors - Error if we are not adhering to the standard (like -std=c++11 or -std=c++14)
• -Wold-style-cast - https://clang.llvm.org/docs/DiagnosticsReference.html#id449
• -Wno-error=unused-variable - warn on unused variables, but don't error: this is to make development less painful. The assumption is that you'll see these warnings while developing and fix them eventually.

Note: all the above flags ARE NOT turned on by default in clang++ (according to https://clang.llvm.org/docs/DiagnosticsReference.html). If they were then there would be no need to list them explicitly.

My proposal for 🍊 is:

• -Wshadow - Clang++ shadow warnings are useful while GCC tends to spit out a lot of spurious ones. Developers of large code bases that support GCC may wish to not enable this warning. Developers of small code bases should.
• -Wfloat-equal - Comparing floats should be done with an epsilon. This is ideal when you are starting new code and might be very painful to enable for large codebases. See https://github.com/mapbox/wagyu/commit/737760b59e0661fc73e45f962c5e9e2dfc627e69 and https://github.com/mapnik/mapnik/issues/3357 for context.
• -Weffc++ - useful when building with g++ (does not do much with clang++). With g++ it can catch uninitialized class members and prevent crashes like https://github.com/mapbox/wagyu/pull/69 - refs https://github.com/mapbox/wagyu/pull/70

My proposal for 🍏 is:

• -Weverything
• -Wno-c++98-compat-pedantic
• -Wno-c++98-compat

🍎 proposal is:

clang++ only

• -Wmost

g++ only

TODO: develop our recommended list based on testing https://kristerw.blogspot.de/2017/09/useful-gcc-warning-options-not-enabled.html

[joto]

One important tip here: All code that is #included from somewhere outside your own code should be included as system library by having the right include path configuration. Use -isystem <DIR> instead of -I <DIR> for this on compiler command lines, in CMake it is include_directories(SYSTEM <DIR>) instead of include_directories(<DIR>). This way warnings are not reported from those libraries. Otherwise you often have to disable warnings for code in libraries you don't have control over. For instance I usually have a copy of catch.hpp in my code for testing, but I put it into its own directory separate from my own headers.

[daniel-j-h]

I want to flag the following:

• https://kristerw.blogspot.de/2017/09/useful-gcc-warning-options-not-enabled.html
• Clang's -Wmost
• Clang's warning flags as a tree to see subsets https://gist.github.com/d0k/3608547

[springmeyer]

Thanks @joto: Absolutely agree that, to allow more aggressive warnings in your code (and especially -Werror), this must be paired with using -isystem or include_directories(SYSTEM <DIR>) for deps you don't control. As a few examples, I've done this at https://github.com/mapbox/node-cpp-skel/pull/42 and https://github.com/mapbox/hpp-skel/blob/0af4ae29ec83fe12db20963fcd0855dbe7708a57/CMakeLists.txt#L30.

@daniel-j-h - thanks for these links. So far the flags I'm recommending above work in both recent g++ and clang++. Your links raise the issue that it would be useful to also develop recommended lists of additional warnings to enable, per compiler. I will edit inline above to add another section specific to compilers. Then I will plan to PR a doc that will list these and we can iterate on that doc.

[springmeyer]

refs https://github.com/Project-OSRM/osrm-backend/pull/4843