Marking as deprecated in C++14

The upcoming C++14 standard introduces an attribute for marking declarations as deprecated, useful for discouraging any use of the declared entity.

It is common for entities in source code (functions, classes, etc.) to become obsolete or unsafe as a project undergoes development. It's usually a bad idea to remove those entities without any warning, as it'll break any code that interfaces with those entities. Instead, a good practice is to mark them as deprecated in an attempt to discourage their use.

The upcoming C++ release, C++14, introduces the deprecated attribute for specifying that an entity is deprecated. The compiler can then emit warnings whenever these entities are being used. In general, attributes are given as a comma-separated list in double square brackets and can be used in various locations. For example, we can deprecate a function by placing the deprecated attribute at the very beginning of the function declaration:

[[deprecated]]voidfoo(){}intmain(){foo();// we're using a deprecated function}

Other existing attributes include noreturn, carries_dependency, and alignas (which has a different syntax).

Compiled with the latest build of clang, this gives the following warning:

The deprecated attribute can also be applied to classes, typedefs, variables, non-static data members, enumerations, and template specializations. Here's a bunch of examples:

// Deprecate a function[[deprecated]]voidfoo();// Deprecate a variable[[deprecated]]intx;// Deprecate one declarator in a multi-declarator declarationinty[[deprecated]],z;// Deprecate a function parameterinttriple([[deprecated]]intx);// Deprecate a class (or struct)class[[deprecated]]my_class{public:// Deprecate a member[[deprecated]]intmember;};// Deprecate an enumenum[[deprecated]]animals{CAT,DOG,MOUSE};// Deprecate a typedef[[deprecated]]typedefinttype;// Deprecate a template specializationtemplate<typenameT>classtempl;template<>class[[deprecated]]templ<int>{};

For those who are curious about the seemingly inconsistent placement of attributes, such as them appearing after the class and enum keywords, it is to distinguish between the deprecation of such a type and the deprecation of a variable of that type. For example, the following deprecates the variable c and not the class itself:

[[deprecated]]classC{}c;

The deprecated attribute need only appear on a single declaration of a particular name or entity in order to mark it as deprecated. That is, later redeclaring without the attribute does not “undeprecate” the declaration. Placing the attribute in a header file declaration will ensure that it appears deprecated to all users of this header file.