[Development] Upgrading the sources to C++11 keywords (Q_NULLPTR, etc.)

[Thiago Macieira]

Hello

I think it's time to institute a policy that we should fix our sources to use 
the new C++11 keywords. I'd like to propose the following.

Policy per keyword:

 * Q_NULLPTR - strongly encouraged

Use it whenever your literal zero is a null pointer. You can leave it out when 
it cannot be mistaken for a zero and it would otherwise make the source code 
harder to read.

Note that Qt still compiles with C++98, so you can't use Q_NULLPTR for 
disambiguation. For example, the new QIODevice::readLine overloads

	QByteArray readLine(qint64 maxSize);
	bool readLine(QByteArray *line, qint64 maxSize = -1);

In C++11, you could write
	if (dev.readLine(Q_NULLPTR))	// read a line and discard

But the code above would be ambiguous in C++98, so you can't use it.

Special: update code using Q_NULLPTR as you would update whitespace.

 * Q_DECL_EQ_DEFAULT - really discouraged

I can't think of any case where you could use this and let the code still 
compile in C++98, so don't use it

 * Q_DECL_EQ_DELETE - strongly encouraged, use with care

Let's the compiler print an error instead of allowing a linker error for an 
unresolved symbol.

 * Q_DECL_CONSTEXPR / Q_DECL_RELAXED_CONSTEXPR - strongly encouraged

Use where it makes sense. If possible, use the C++11 restricted constexpr as 
we have still too few compilers with C++14 relaxed constexpr support (Clang 
3.5, GCC 5), but feel free to use Q_DECL_RELAXED_CONSTEXPR when there's benefit 
for constexprness but impossible to solve in C++11

 * Q_DECL_FINAL - optional, use with care

There's a small benefit in optimisation by devirtualising calls. Use it with 
care.

Use in public classes is discouraged, since people can compile with a C++98 
and derive / override what they shouldn't.

 * Q_DECL_OVERRIDE - required in new code, don't add to old code

Always add Q_DECL_OVERRIDE for any override in new classes you write. This 
supersedes the need for the "virtual" keyword -- add it or not, it's up to 
you.

DO NOT add to existing classes, including for new overrides to existing 
classes. Clang 3.6 has a new warning about inconsistent use of this keyword, 
so adding to one place requires adding to all overrides in that class. 
Therefore, this needs to be done fully in each class and that's not a 
"whitespace correction" error.

 * Q_CONSTEXPR - use only where required

You probably don't need this. You'll need it when accessing const data from a 
Q_DECL_CONSTEXPR function. Otherwise, you won't need it.

You could use this to create a static-initialisation-time const variable of a 
non-POD type, but since our sources still compile in C++98 and we still have a 
rule against non-POD statics, you should not do this.

 * Q_DECL_NOTHROW / Q_DECL_NOEXCEPT - strongly encouraged

To public functions (all modules); any function in modules compiled with 
exception (QtCore, QtXmlPatterns, QtConcurrent).

You probably want Q_DECL_NOTHROW instead of Q_DECL_NOEXCEPT.

Do not add to functions that:
 * allocate memory
 * call functions that may throw, especially user functions
 * call POSIX cancellation points
 * have narrow contracts -- that is, you could conceivably add a Q_ASSERT on 
   input parameters

If the function is an inline template function and the exception depends on 
the template argument, use Q_DECL_NOEXCEPT_EXPR.

Non-C++11 but also useful:

 * Q_DECL_{PURE,CONST}_FUNCTION - encouraged

A pure function is a function that will return the same value if called twice 
with the same parameters. Pure functions are allowed to read from pointers 
passed to it, including the "this" pointer. Pure functions are not allowed to 
have observable side-effects (rule of thumb: no writing to dereferenced 
pointers or to global variables).

A const function is a function that is pure and does not dereference any 
pointers.

Quite by definition, const and pure functions cannot return void. Any such 
calls would be discarded by the compiler.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center