How to Toggle Enabling or Disabling of Deprecated Code

Introduction

“To Err is Human, to Deprecate is Divine…”

Shakespeare (paraphrased)

From time to time, we realise that our previous decisions were a mistake, that we don’t want to carry with us in the future. We also don’t want to strand our users, who are currently relying on the old code working the way that it does.

Here’s how Approval Tests deals with deprecations.

Deprecation Mechanics

When enabled, these deprecation warnings will show up as:

compiler C++14 and above, using the [[deprecated("..."]] feature
messages on std::cout in C++11

Opting in

Show warnings

To opt in to warnings, add this line to your C++ code:

#define APPROVAL_TESTS_SHOW_DEPRECATION_WARNINGS 1

(See snippet source)

Or this to your CMakeLists.txt:

# Replace ${PROJECT_NAME} with the name of your test executable:
target_compile_definitions(${PROJECT_NAME} PRIVATE -DAPPROVAL_TESTS_SHOW_DEPRECATION_WARNINGS=1)

(See snippet source)

Hide deprecated code

A more extreme version of this is to not even compile the deprecated code. You can do this by adding this line:

#define APPROVAL_TESTS_HIDE_DEPRECATED_CODE 1

(See snippet source)

Or this to your CMakeLists.txt:

# Replace ${PROJECT_NAME} with the name of your test executable:
target_compile_definitions(${PROJECT_NAME} PRIVATE -DAPPROVAL_TESTS_HIDE_DEPRECATED_CODE=1)

(See snippet source)

How to Update Calls to Deprecated Code

Whenever we deprecate a method, the implementation of the deprecated method will always contain a single line, which is how we want the code to be called in the future.

As such, you can always open up the method to see how to convert your code.

If you IDE supports inlining, you can also select your old function call, and inline just that one line, and your IDE will update the code for you.

Note If you are reading this after we have removed the deprecated methods, please download a slightly earlier release, and then follow one of the steps above.