[[deprecated]] 不是贴纸，是写给未来自己的便条

上周帮同事看一段老代码，发现一个函数被加了 [[deprecated]]，但调用它的地方没任何提示，编译也安静得像什么都没发生。他挠头问我：“这标记是不是失效了？”——其实不是失效，是很多人把它当成了“仅供观赏”的装饰标签。

[[deprecated]] 是 C++14 引入的标准属性，它的本意从来不是“等你哪天想起来再改”，而是主动介入开发流程，在错误发生前就亮起黄灯。可现实里，它常被用成一句轻飘飘的注释：“这个别用了”，却没说清“为什么不能用”“该换成什么”“不换会怎样”。

真正用好它，需要三个动作：标得准、说得清、拦得住。

先说“标得准”。属性必须紧贴被废弃的声明，且位置不能错。比如：

// ✅ 正确：直接修饰函数声明
[[deprecated("请改用 process_v2(const std::string&)")]]
void process(const char* s);

// ❌ 错误：放在定义处（编译器通常忽略）
void process(const char* s) {
    [[deprecated]] // 这里无效！属性作用域仅限于声明
    ...
}

很多人栽在第一个坑：把 [[deprecated]] 加在实现里，或者加在类内部的私有成员上却忘了对外部接口同步标记。结果是调用方毫无感知——因为编译器只检查可见声明。标记的位置，决定了警告能否被看见。

再说“说得清”。空括号 [[deprecated]] 是最低效的写法。它只触发警告，却不告诉开发者任何迁移路径。而带字符串字面量的版本，才是真正的协作语言：

[[deprecated("v1 接口已移除缓冲区拷贝优化；请迁移到 process_span(std::span<const uint8_t>)，性能提升约 3.2x")]]
std::vector<uint8_t> encode_legacy(const std::string& input);

这段话里藏着三重信息：旧问题在哪（无优化）、新方案是什么（process_span）、收益有多大（3.2x）。团队新人第一次见到这个警告，不用翻文档、不用问人，就能判断要不要立刻改、值不值得改。废弃提示不是甩锅，是降低认知负荷的最小交接包。

最后是“拦得住”。默认情况下，[[deprecated]] 只产生 warning，而很多项目默认不把 warning 当 error。这就导致警告被忽略——尤其在 CI 流水线里，warning 常被静默吞掉。解决办法很实在：在构建系统中启用 -Werror=deprecated-declarations（GCC/Clang）或 /we4996（MSVC）。一旦启用，所有废弃调用立即编译失败。这不是制造麻烦，而是把“技术债”从运行时风险提前锁死在编译阶段。

还有一点容易被忽略：[[deprecated]] 对模板实例化同样生效，但只对显式特化或具体实例起作用。比如：

template<typename T>
[[deprecated]] void helper(T x); // 这个声明本身不会触发警告

helper<int>(42); // ✅ 触发警告：实例化后声明可见

但如果模板参数是推导出来的（如 helper(42)），部分编译器可能不报——这是标准允许的宽松行为。所以涉及模板的废弃，最好配合 SFINAE 或 static_assert 做双重保险。

实际项目中，我们还发现一个高频场景：API 版本迭代。比如 v2.0 移除了某个回调参数。与其等用户升级后崩溃，不如在 v1.9 就加上：

[[deprecated("on_error 参数将在 v2.0 中移除；错误现在统一通过返回 std::expected<T, Error> 传达")]]
void fetch_data(std::string_view url, std::function<void()> on_success,
                std::function<void()> on_error); // ← 这个参数即将消失

这样，用户在升级前就收到明确信号，甚至能用 IDE 的“查找所有引用”快速定位待修改点。废弃标记不是终点，而是平滑过渡的起点。

顺带提一句：[[deprecated]] 和 #pragma deprecated 不同。后者是非标准、编译器私有的，跨平台维护成本高；前者是 ISO 标准，C++14 起所有主流编译器都支持，连 MSVC 从 2015 Update 3 开始也完整实现了。选标准属性，就是选长期可维护性。

当然，它也不是万能胶。如果一个函数被废弃了三年还没人动，那大概率不是标记没用，而是团队缺乏跟进机制。我们会在周会固定花五分钟过一遍 git grep "\[\[deprecated\]\]" 的结果，确认每个标记都有对应 issue 编号和负责人。属性不会自动清理代码，但能让人没法假装看不见。

写到最后想说：[[deprecated]] 最珍贵的价值，不是告诉别人“这个错了”，而是提醒自己——今天加上的每一行废弃标记，都是明天少踩的一个坑，也是对后来者最朴素的体谅。它不华丽，但够诚恳；不强制，却有分量。