Deprecation messages and templates

Since there's not currently a way to give a message with deprecated or to mark something as scheduled for deprecation (regardless of whether there's a message), the only way that I'm aware of to give a message when someone uses a symbol which has been deprecated or scheduled for deprecation (other than the error you get when using a deprecated symbol without -d) is to use a pragma. And the only way to restrict a pragma such that it's printed only when the symbol it's associated with is actually used is to have that symbol be templated and put the pragma in the template. That's how we've generally been handling deprecation messages. It does pose one problem, however, which hadn't occurred to me. If the function wasn't templated before and we make it templated (albeit with the constraint restricting its arguments to what they were before), you can no longer pass the function as a predicate to other functions such as filter or sort (at least, not without changing your code to explicitly instantiate them, and the whole point of the message prior to actually deprecating them was to avoid breaking code).

So, the question that this raises is: In cases where adding a deprecation message requires templatizing a currently untemplatized function where that function's signature is such that there's a decent chance that it was passed as a predicate to another function and therefore templatizing it would break such code, should we just avoid templatizing it and only put the deprecation message in the documentation? Or should we just templatize it, and while some code might break due to the change, any code which doesn't use the function as a predicate should be fine?

I'm torn. I'd very much like the deprecation message to print, and I _don't_ want it to print if the deprecated (or scheduled to be deprecated) symbol isn't actually used. If there's no message printed, the only way that anyone is going to realize that the function is being deprecated is if they read its documentation, which they probably aren't going to do, since they're already using the function, so the waiting period prior to actually deprecating the symbol is next-to-useless. On the other hand, if the function is templated and some code does break, then for those cases, it's pretty much just as if we had immediately deprecated the symbol rather than scheduling it for deprecation. So, I really don't know which to do. In cases where a function clearly wouldn't be used as a predicate, I'd definitely templatize it, but in cases where it probably would be (such as a function like std.ctype.isdigit), there's a high risk of breaking code.

If deprecated were improved to include a message and to allow for soft deprecation (i.e. scheduled for deprecation), then that solves the problem quite neatly. We wouldn't have to be hacky about it with pragmas anymore, but that would likely take some work to implement, and we may not have such an improvement anytime soon. So, we need to decide on what we're going to do as long as we just have pragmas.

Should we favor putting the deprecation message in the documentation only where it will likely have almost no effect and thus only delay the surprise of code breaking when the function is deprecated, or should we favor templatizing them and avoid the surprise for the cases where the templatization doesn't matter but immediately surprise those who used the function as a predicate? Both solutions suck IMHO, but I don't see any other options (other than just not deprecating some stuff, but that means that we're stuck with code that needs to be fixed until deprecated is improved, which would just increase the cost of deprecating stuff, since it will have been used that much longer and by that many more people and so more code will break when the change is made).

- Jonathan M Davis

P.S. This post seems a bit long, now that I've typed it. That seems to happen a lot. I should probably learn how to be more concise one of these days...

Forums